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 [2/5] -
/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ChoiceFormat.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ChoiceFormat.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ChoiceFormat.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ChoiceFormat.java Thu May 7 08:42:00 2009
@@ -23,11 +23,50 @@
import java.util.Locale;
/**
- * ChoiceFormat is used to associate strings with ranges of double values. The
- * strings and ranges are either specified using arrays or with a pattern which
- * is parsed to determine the Strings and ranges.
+ * Returns a fixed string based on a numeric value. The class can be used in
+ * conjunction with the {@link MessageFormat} class to handle plurals in
+ * messages. {@code ChoiceFormat} enables users to attach a format to a range of
+ * numbers. The choice is specified with an ascending list of doubles, where
+ * each item specifies a half-open interval up to the next item as in the
+ * following: X matches j if and only if {@code limit[j] <= X < limit[j+1]}.
+ * <p>
+ * If there is no match, then either the first or last index is used. The first
+ * or last index is used depending on whether the number is too low or too high.
+ * The length of the format array must be the same as the length of the limits
+ * array.
+ * <h5>Examples:</h5>
+ * <blockquote>
+ *
+ * <pre>
+ * double[] limits = {1, 2, 3, 4, 5, 6, 7};
+ * String[] fmts = {"Sun", "Mon", "Tue", "Wed", "Thur", "Fri", "Sat"};
+ *
+ * double[] limits2 = {0, 1, ChoiceFormat.nextDouble(1)};
+ * String[] fmts2 = {"no files", "one file", "many files"};
+ * </pre>
+ * </blockquote>
+ * <p>
+ * ChoiceFormat.nextDouble(double) allows to get the double following the one
+ * passed to the method. This is used to create half open intervals.
+ * <p>
+ * {@code ChoiceFormat} objects also may be converted to and from patterns.
+ * The conversion can be done programmatically, as in the example above, or
+ * by using a pattern like the following:
+ * <blockquote>
+ *
+ * <pre>
+ * "1#Sun|2#Mon|3#Tue|4#Wed|5#Thur|6#Fri|7#Sat"
+ * "0#are no files|1#is one file|1<are many files"
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * where:
+ * <ul>
+ * <li><number>"#"</number> specifies an inclusive limit value;</li>
+ * <li><number>"<"</number> specifies an exclusive limit value.</li>
+ * </ul>
*/
-
public class ChoiceFormat extends NumberFormat {
private static final long serialVersionUID = 1795184449645032964L;
@@ -37,31 +76,35 @@
private String[] choiceFormats;
/**
- * Constructs a new ChoiceFormat with the specified ranges and associated
- * strings.
- *
+ * Constructs a new {@code ChoiceFormat} with the specified double values
+ * and associated strings. When calling
+ * {@link #format(double, StringBuffer, FieldPosition) format} with a double
+ * value {@code d}, then the element {@code i} in {@code formats} is
+ * selected where {@code i} fulfills {@code limits[i] <= d < limits[i+1]}.
+ * <p>
+ * The length of the {@code limits} and {@code formats} arrays must be the
+ * same.
+ *
* @param limits
- * an array of double, the ranges are greater or equal to the
- * value in lower index up to less than the value in the next
- * higher index. The bounds of the lowest and highest indexes are
- * negative and positive infinity.
+ * an array of doubles in ascending order. The lowest and highest
+ * possible values are negative and positive infinity.
* @param formats
- * the strings associated with the ranges. The lower bound of the
- * associated range is at the same index as the string.
+ * the strings associated with the ranges defined through {@code
+ * limits}. The lower bound of the associated range is at the
+ * same index as the string.
*/
public ChoiceFormat(double[] limits, String[] formats) {
setChoices(limits, formats);
}
/**
- * Constructs a new ChoiceFormat with the strings and ranges parsed from the
- * specified pattern.
+ * Constructs a new {@code ChoiceFormat} with the strings and limits parsed
+ * from the specified pattern.
*
* @param template
- * the pattern of strings and ranges
- *
- * @exception IllegalArgumentException
- * then an error occurs parsing the pattern
+ * the pattern of strings and ranges.
+ * @throws IllegalArgumentException
+ * if an error occurs while parsing the pattern.
*/
public ChoiceFormat(String template) {
applyPattern(template);
@@ -69,13 +112,12 @@
/**
* Parses the pattern to determine new strings and ranges for this
- * ChoiceFormat.
+ * {@code ChoiceFormat}.
*
* @param template
- * the pattern of strings and ranges
- *
- * @exception IllegalArgumentException
- * then an error occurs parsing the pattern
+ * the pattern of strings and ranges.
+ * @throws IllegalArgumentException
+ * if an error occurs while parsing the pattern.
*/
public void applyPattern(String template) {
double[] limits = new double[5];
@@ -140,10 +182,10 @@
}
/**
- * Answers a new instance of ChoiceFormat with the same ranges and strings
- * as this ChoiceFormat.
+ * Returns a new instance of {@code ChoiceFormat} with the same ranges and
+ * strings as this {@code ChoiceFormat}.
*
- * @return a shallow copy of this ChoiceFormat
+ * @return a shallow copy of this {@code ChoiceFormat}.
*
* @see java.lang.Cloneable
*/
@@ -156,15 +198,14 @@
}
/**
- * Compares the specified object to this ChoiceFormat and answer if they are
- * equal. The object must be an instance of ChoiceFormat and have the same
- * limits and formats.
+ * Compares the specified object with this {@code ChoiceFormat}. The object
+ * must be an instance of {@code ChoiceFormat} and have the same limits and
+ * formats to be equal to this instance.
*
* @param object
- * the object to compare with this object
- * @return true if the specified object is equal to this ChoiceFormat, false
- * otherwise
- *
+ * the object to compare with this instance.
+ * @return {@code true} if the specified object is equal to this instance;
+ * {@code false} otherwise.
* @see #hashCode
*/
@Override
@@ -181,16 +222,16 @@
}
/**
- * Appends to the specified StringBuffer the string associated with the
- * range in which the specified double value fits.
+ * Appends the string associated with the range in which the specified
+ * double value fits to the specified string buffer.
*
* @param value
- * the double to format
+ * the double to format.
* @param buffer
- * the StringBuffer
+ * the target string buffer to append the formatted value to.
* @param field
- * a FieldPosition which is ignored
- * @return the StringBuffer parameter <code>buffer</code>
+ * a {@code FieldPosition} which is ignored.
+ * @return the string buffer.
*/
@Override
public StringBuffer format(double value, StringBuffer buffer,
@@ -205,16 +246,16 @@
}
/**
- * Appends to the specified StringBuffer the string associated with the
- * range in which the specified long value fits.
+ * Appends the string associated with the range in which the specified long
+ * value fits to the specified string buffer.
*
* @param value
- * the long to format
+ * the long to format.
* @param buffer
- * the StringBuffer
+ * the target string buffer to append the formatted value to.
* @param field
- * a FieldPosition which is ignored
- * @return the StringBuffer parameter <code>buffer</code>
+ * a {@code FieldPosition} which is ignored.
+ * @return the string buffer.
*/
@Override
public StringBuffer format(long value, StringBuffer buffer,
@@ -223,31 +264,30 @@
}
/**
- * Answers the Strings associated with the ranges of this ChoiceFormat.
+ * Returns the strings associated with the ranges of this {@code
+ * ChoiceFormat}.
*
- * @return an array of String
+ * @return an array of format strings.
*/
public Object[] getFormats() {
return choiceFormats;
}
/**
- * Answers the ranges of this ChoiceFormat.
+ * Returns the limits of this {@code ChoiceFormat}.
*
- * @return an array of double, the ranges are greater or equal to the value
- * in lower index up to less than the value in the next higher
- * index. The bounds of the lowest and highest indexes are negative
- * and positive infinity.
+ * @return the array of doubles which make up the limits of this {@code
+ * ChoiceFormat}.
*/
public double[] getLimits() {
return choiceLimits;
}
/**
- * Answers an integer hash code for the receiver. Objects which are equal
- * answer the same value for this method.
+ * Returns an integer hash code for the receiver. Objects which are equal
+ * return the same value for this method.
*
- * @return the receiver's hash
+ * @return the receiver's hash.
*
* @see #equals
*/
@@ -262,12 +302,12 @@
}
/**
- * Answers the double value which is closest to the specified double but
+ * Returns the double value which is closest to the specified double but
* larger.
*
* @param value
- * a double value
- * @return the next larger double value
+ * a double value.
+ * @return the next larger double value.
*/
public static final double nextDouble(double value) {
if (value == Double.POSITIVE_INFINITY) {
@@ -284,32 +324,49 @@
}
/**
- * Answers the double value which is closest to the specified double but
+ * Returns the double value which is closest to the specified double but
* either larger or smaller as specified.
*
* @param value
- * a double value
+ * a double value.
* @param increment
- * true to get a larger value, false to get a smaller value
- * @return the next larger or smaller double value
+ * {@code true} to get the next larger value, {@code false} to
+ * get the previous smaller value.
+ * @return the next larger or smaller double value.
*/
public static double nextDouble(double value, boolean increment) {
return increment ? nextDouble(value) : previousDouble(value);
}
/**
- * Parse a Double from the specified String starting at the index specified
- * by the ParsePosition. The String is compared to the strings of this
- * ChoiceFormat and if a match occurs, the answer is the lower bound of the
- * corresponding range. If the string is successfully parsed, the index of
- * the ParsePosition is updated to the index following the parsed text.
- *
+ * Parses a double from the specified string starting at the index specified
+ * by {@code position}. The string is compared to the strings of this
+ * {@code ChoiceFormat} and if a match occurs then the lower bound of the
+ * corresponding range in the limits array is returned. If the string is
+ * successfully parsed then the index of the {@code ParsePosition} passed to
+ * this method is updated to the index following the parsed text.
+ * <p>
+ * If one of the format strings of this {@code ChoiceFormat} instance is
+ * found in {@code string} starting at {@code position.getIndex()} then
+ * <ul>
+ * <li>the index in {@code position} is set to the index following the
+ * parsed text;
+ * <li>the {@link java.lang.Double Double} corresponding to the format
+ * string is returned.</li>
+ * </ul>
+ * <p>
+ * If none of the format strings is found in {@code string} then
+ * <ul>
+ * <li>the error index in {@code position} is set to the current index in
+ * {@code position};</li>
+ * <li> {@link java.lang.Double#NaN Double.NaN} is returned.
+ * </ul>
* @param string
- * the String to parse
+ * the source 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
+ * input/output parameter, specifies the start index in {@code
+ * string} from where to start parsing. See the <em>Returns</em>
+ * section for a description of the output values.
* @return a Double resulting from the parse, or Double.NaN if there is an
* error
*/
@@ -327,12 +384,12 @@
}
/**
- * Answers the double value which is closest to the specified double but
+ * Returns the double value which is closest to the specified double but
* smaller.
*
* @param value
- * a double value
- * @return the next smaller double value
+ * a double value.
+ * @return the next smaller double value.
*/
public static final double previousDouble(double value) {
if (value == Double.NEGATIVE_INFINITY) {
@@ -349,16 +406,22 @@
}
/**
- * Sets the ranges and associated strings of this ChoiceFormat.
- *
+ * Sets the double values and associated strings of this ChoiceFormat. When
+ * calling {@link #format(double, StringBuffer, FieldPosition) format} with
+ * a double value {@code d}, then the element {@code i} in {@code formats}
+ * is selected where {@code i} fulfills
+ * {@code limits[i] <= d < limits[i+1]}.
+ * <p>
+ * The length of the {@code limits} and {@code formats} arrays must be the
+ * same.
+ *
* @param limits
- * an array of double, the ranges are greater or equal to the
- * value in lower index up to less than the value in the next
- * higher index. The bounds of the lowest and highest indexes are
- * negative and positive infinity.
+ * an array of doubles in ascending order. The lowest and highest
+ * possible values are negative and positive infinity.
* @param formats
- * the strings associated with the ranges. The lower bound of the
- * range is at the same index as the string.
+ * the strings associated with the ranges defined through {@code
+ * limits}. The lower bound of the associated range is at the
+ * same index as the string.
*/
public void setChoices(double[] limits, String[] formats) {
if (limits.length != formats.length) {
@@ -377,10 +440,10 @@
}
/**
- * Answers the pattern of this ChoiceFormat which specified the ranges and
- * their associated strings.
+ * Returns the pattern of this {@code ChoiceFormat} which specifies the
+ * ranges and their associated strings.
*
- * @return the pattern
+ * @return the pattern.
*/
public String toPattern() {
StringBuffer buffer = new StringBuffer();
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationElementIterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationElementIterator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationElementIterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationElementIterator.java Thu May 7 08:42:00 2009
@@ -18,62 +18,35 @@
package java.text;
/**
- * <p>
- * <code>CollationElementIterator</code> is created by a
- * <code>RuleBasedCollator</code> to iterate through a string. The return
+ * Created by a {@code RuleBasedCollator} to iterate through a string. The
* result of each iteration is a 32-bit collation element that defines the
* ordering priority of the next character or sequence of characters in the
* source string.
- * </p>
* <p>
* For illustration, consider the following in Spanish:
- * </p>
- *
* <p>
- * <code>
- * "ca" -> the first collation element is collation_element('c') and second
+ * "ca": the first collation element is collation_element('c') and second
* collation element is collation_element('a').
- * </code>
- * </p>
- *
- * <p>
- * <code>
- * Since "ch" in Spanish sorts as one entity, the below example returns one
- * collation element for the two characters 'c' and 'h'
- * </code>
- * </p>
- *
* <p>
- * <code>
- * "cha" -> the first collation element is collation_element('ch') and second
- * collation element is collation_element('a').
- * </code>
- * </p>
+ * Since "ch" in Spanish sorts as one entity, the example below returns one
+ * collation element for the two characters 'c' and 'h':
+ * <p>
+ * "cha": the first collation element is collation_element('ch') and the second
+ * one is collation_element('a').
+ * <p>
+ * In German, since the character '\u0086' is a composed character of 'a'
+ * and 'e', the iterator returns two collation elements for the single character
+ * '\u0086':
* <p>
- * And in German,
- * </p>
- *
- * <p>
- * <code>
- * Since the character '\u0086' is a composed character of 'a' and 'e', the iterator
- * returns two collation elements for the single character '\u0086'
- * </code>
- * </p>
- * <p>
- * <code>
- * "\u0086b" -> the first
- * collation element is collation_element('a'), the second collation element is
- * collation_element('e'), and the third collation element is
+ * "\u0086b": the first collation element is collation_element('a'), the
+ * second one is collation_element('e'), and the third collation element is
* collation_element('b').
- * </code>
- * </p>
- *
*/
public final class CollationElementIterator {
/**
* This constant is returned by the iterator in the methods
- * <code>next()</code> and <code>previous()</code> when the end or the
+ * {@code next()} and {@code previous()} when the end or the
* beginning of the source string has been reached, and there are no more
* valid collation elements to return.
*/
@@ -87,8 +60,8 @@
/**
* Obtains the maximum length of any expansion sequence that ends with the
- * specified collation element. If there is no expansion with this collation
- * element as the last element, returns <code>1</code>.
+ * specified collation element. Returns {@code 1} if there is no expansion
+ * with this collation element as the last element.
*
* @param order
* a collation element that has been previously obtained from a
@@ -103,23 +76,25 @@
/**
* Obtains the character offset in the source string corresponding to the
- * next collation element. This value could be any of: <ui>
+ * next collation element. This value could be any of:
+ * <ul>
* <li>The index of the first character in the source string that matches
- * the value of the next collation element. (This means that if
- * setOffset(offset) sets the index in the middle of a contraction,
- * getOffset() returns the index of the first character in the contraction,
- * which may not be equal to the original offset that was set. Hence calling
- * getOffset() immediately after setOffset(offset) does not guarantee that
- * the original offset set will be returned.)</li>
+ * the value of the next collation element. This means that if
+ * {@code setOffset(offset)} sets the index in the middle of a contraction,
+ * {@code getOffset()} returns the index of the first character in the
+ * contraction, which may not be equal to the original offset that was set.
+ * Hence calling {@code getOffset()} immediately after
+ * {@code setOffset(offset)} does not guarantee that the original offset set
+ * will be returned.</li>
* <li>If normalization is on, the index of the immediate subsequent
* character, or composite character with the first character, having a
* combining class of 0.</li>
* <li>The length of the source string, if iteration has reached the end.
* </li>
- * <ui>
+ * </ul>
*
* @return The position of the collation element in the source string that
- * will be returned in the next invocation of the {@link #next()}
+ * will be returned by the next invocation of the {@link #next()}
* method.
*/
public int getOffset() {
@@ -129,7 +104,7 @@
/**
* Obtains the next collation element in the source string.
*
- * @return the next collation element or <code>NULLORDER</code> if the end
+ * @return the next collation element or {@code NULLORDER} if the end
* of the iteration has been reached.
*/
public int next() {
@@ -139,7 +114,7 @@
/**
* Obtains the previous collation element in the source string.
*
- * @return the previous collation element, or <code>NULLORDER</code> when
+ * @return the previous collation element, or {@code NULLORDER} when
* the start of the iteration has been reached.
*/
public int previous() {
@@ -151,7 +126,8 @@
* first 16 bits. This value is unsigned.
*
* @param order
- * @return the element's 16 bits primary order.
+ * the element of the collation.
+ * @return the element's 16 bit primary order.
*/
public static final int primaryOrder(int order) {
return com.ibm.icu.text.CollationElementIterator.primaryOrder(order);
@@ -159,14 +135,12 @@
/**
* Repositions the cursor to point at the first element of the current
- * string. The next call to <code>next()</code> or <code>previous()</code>
- * will return the first and last collation element in the string,
- * respectively.
+ * string. The next call to {@link #next()} or {@link #previous()} will
+ * return the first and last collation element in the string, respectively.
* <p>
- * If the <code>RuleBasedCollator</code> used by this iterator has had its
- * attributes changed, calling <code>reset()</code> will reinitialize the
- * iterator to use the new attributes.
- * </p>
+ * If the {@code RuleBasedCollator} used by this iterator has had its
+ * attributes changed, calling {@code reset()} reinitializes the iterator to
+ * use the new attributes.
*/
public void reset() {
this.icuIterator.reset();
@@ -177,7 +151,8 @@
* 16th to 23th bits, inclusive. This value is unsigned.
*
* @param order
- * @return the 8 bit secondary order of the element
+ * the element of the collator.
+ * @return the 8 bit secondary order of the element.
*/
public static final short secondaryOrder(int order) {
return (short) com.ibm.icu.text.CollationElementIterator
@@ -190,18 +165,16 @@
* After this call completes, an invocation of the {@link #next()} method
* will return this collation element.
* <p>
- * If <code>newOffset</code> corresponds to a character which is part of a
- * sequence that maps to a single collation element the iterator is adjusted
- * to the start of that sequence. As a result of this, any subsequent call
- * made to <code>getOffset()</code> may not return the same value set by
- * this method.
- * </p>
+ * If {@code newOffset} corresponds to a character which is part of a
+ * sequence that maps to a single collation element then the iterator is
+ * adjusted to the start of that sequence. As a result of this, any
+ * subsequent call made to {@code getOffset()} may not return the same value
+ * set by this method.
* <p>
* If the decomposition mode is on, and offset is in the middle of a
* decomposable range of source text, the iterator may not return a correct
* result for the next forwards or backwards iteration. The user must ensure
* that the offset is not in the middle of a decomposable range.
- * </p>
*
* @param newOffset
* the character offset into the original source string to set.
@@ -213,7 +186,7 @@
}
/**
- * Sets a new source string iterator for iteration, and reset the offset to
+ * Sets a new source string iterator for iteration, and resets the offset to
* the beginning of the text.
*
* @param source
@@ -224,11 +197,11 @@
}
/**
- * Sets a new source string for iteration, and reset the offset to the
+ * Sets a new source string for iteration, and resets the offset to the
* beginning of the text.
*
* @param source
- * the new source string for iteration
+ * the new source string for iteration.
*/
public void setText(String source) {
this.icuIterator.setText(source);
@@ -239,7 +212,8 @@
* last 8 bits. This value is unsigned.
*
* @param order
- * @return the 8 bits tertiary order of the element
+ * the element of the collation.
+ * @return the 8 bit tertiary order of the element.
*/
public static final short tertiaryOrder(int order) {
return (short) com.ibm.icu.text.CollationElementIterator
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationKey.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationKey.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationKey.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationKey.java Thu May 7 08:42:00 2009
@@ -18,10 +18,65 @@
package java.text;
/**
- * CollationKey represents the collation order of a particular String for a
- * specific Collator. CollationKeys can be compared to determine the relative
- * ordering of their source Strings. This is useful when the Strings must be
- * compared multiple times, as in sorting.
+ * Represents a string under the rules of a specific {@code Collator} object.
+ * Comparing two {@code CollationKey} instances returns the relative order of
+ * the strings they represent.
+ * <p>
+ * Since the rule set of collators can differ, the sort orders of the same
+ * string under two different {@code Collator} instances might differ. Hence
+ * comparing collation keys generated from different {@code Collator} instances
+ * can give incorrect results.
+ * <p>
+ * Both the method {@code CollationKey.compareTo(CollationKey)} and the method
+ * {@code Collator.compare(String, String)} compares two strings and returns
+ * their relative order. The performance characteristics of these two approaches
+ * can differ.
+ * <p>
+ * During the construction of a {@code CollationKey}, the entire source string
+ * is examined and processed into a series of bits terminated by a null, that
+ * are stored in the {@code CollationKey}. When
+ * {@code CollationKey.compareTo(CollationKey)} executes, it performs bitwise
+ * comparison on the bit sequences. This can incur startup cost when creating
+ * the {@code CollationKey}, but once the key is created, binary comparisons
+ * are fast. This approach is recommended when the same strings are to be
+ * compared over and over again.
+ * <p>
+ * On the other hand, implementations of
+ * {@code Collator.compare(String, String)} can examine and process the strings
+ * only until the first characters differ in order. This approach is
+ * recommended if the strings are to be compared only once.
+ * <p>
+ * The following example shows how collation keys can be used to sort a
+ * list of strings:
+ * <blockquote>
+ *
+ * <pre>
+ * // Create an array of CollationKeys for the Strings to be sorted.
+ * Collator myCollator = Collator.getInstance();
+ * CollationKey[] keys = new CollationKey[3];
+ * keys[0] = myCollator.getCollationKey("Tom");
+ * keys[1] = myCollator.getCollationKey("Dick");
+ * keys[2] = myCollator.getCollationKey("Harry");
+ * sort(keys);
+ * <br>
+ * //...
+ * <br>
+ * // Inside body of sort routine, compare keys this way
+ * if( keys[i].compareTo( keys[j] ) > 0 )
+ * // swap keys[i] and keys[j]
+ * <br>
+ * //...
+ * <br>
+ * // Finally, when we've returned from sort.
+ * System.out.println(keys[0].getSourceString());
+ * System.out.println(keys[1].getSourceString());
+ * System.out.println(keys[2].getSourceString());
+ * </pre>
+ *
+ * </blockquote>
+ *
+ * @see Collator
+ * @see RuleBasedCollator
*/
public final class CollationKey implements Comparable<CollationKey> {
@@ -35,30 +90,29 @@
}
/**
- * Compare the receiver to the specified CollationKey to determine the
- * relative ordering.
+ * Compares this object to the specified collation key object to determine
+ * their relative order.
*
* @param value
- * a CollationKey
- * @return an int < 0 if this CollationKey is less than the specified
- * CollationKey, 0 if they are equal, and > 0 if this CollationKey
- * is greater
+ * the collation key object to compare this object to.
+ * @return a negative value if this {@code CollationKey} is less than the
+ * specified {@code CollationKey}, 0 if they are equal and a
+ * positive value if this {@code CollationKey} is greater.
*/
public int compareTo(CollationKey value) {
return icuKey.compareTo(value.icuKey);
}
/**
- * Compares the specified object to this CollationKey and answer if they are
- * equal. The object must be an instance of CollationKey and have the same
- * source string and collation key. The instances of CollationKey must have
- * been created by the same Collator.
+ * Compares the specified object to this {@code CollationKey} and indicates
+ * if they are equal. The object must be an instance of {@code CollationKey}
+ * and have the same source string and collation key. Both instances of
+ * {@code CollationKey} must have been created by the same {@code Collator}.
*
* @param object
- * the object to compare with this object
- * @return true if the specified object is equal to this CollationKey, false
- * otherwise
- *
+ * the object to compare to this object.
+ * @return {@code true} if {@code object} is equal to this collation key;
+ * {@code false} otherwise.
* @see #hashCode
*/
@Override
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Collator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Collator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Collator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Collator.java Thu May 7 08:42:00 2009
@@ -25,9 +25,90 @@
import org.apache.harmony.luni.util.PriviAction;
/**
- * Collator is an abstract class which is the root of classes which provide
- * Locale specific String comparison to determine their ordering with respect to
- * each other.
+ * Performs locale-sensitive string comparison. A concrete subclass,
+ * {@link RuleBasedCollator}, allows customization of the collation ordering by
+ * the use of rule sets.
+ * <p>
+ * Following the <a href=http://www.unicode.org>Unicode Consortium</a>'s
+ * specifications for the <a
+ * href="http://www.unicode.org/unicode/reports/tr10/"> Unicode Collation
+ * Algorithm (UCA)</a>, there are 4 different levels of strength used in
+ * comparisons:
+ * <ul>
+ * <li>PRIMARY strength: Typically, this is used to denote differences between
+ * base characters (for example, "a" < "b"). It is the strongest difference.
+ * For example, dictionaries are divided into different sections by base
+ * character.
+ * <li>SECONDARY strength: Accents in the characters are considered secondary
+ * differences (for example, "as" < "às" < "at"). Other differences
+ * between letters can also be considered secondary differences, depending on
+ * the language. A secondary difference is ignored when there is a primary
+ * difference anywhere in the strings.
+ * <li>TERTIARY strength: Upper and lower case differences in characters are
+ * distinguished at tertiary strength (for example, "ao" < "Ao" <
+ * "aò"). In addition, a variant of a letter differs from the base form
+ * on the tertiary strength (such as "A" and "Ⓐ"). Another example is the
+ * difference between large and small Kana. A tertiary difference is ignored
+ * when there is a primary or secondary difference anywhere in the strings.
+ * <li>IDENTICAL strength: When all other strengths are equal, the IDENTICAL
+ * strength is used as a tiebreaker. The Unicode code point values of the NFD
+ * form of each string are compared, just in case there is no difference. For
+ * example, Hebrew cantellation marks are only distinguished at this strength.
+ * This strength should be used sparingly, as only code point value differences
+ * between two strings are an extremely rare occurrence. Using this strength
+ * substantially decreases the performance for both comparison and collation key
+ * generation APIs. This strength also increases the size of the collation key.
+ * </ul>
+ * <p>
+ * This {@code Collator} deals only with two decomposition modes, the canonical
+ * decomposition mode and one that does not use any decomposition. The
+ * compatibility decomposition mode
+ * {@code java.text.Collator.FULL_DECOMPOSITION} is not supported here. If the
+ * canonical decomposition mode is set, {@code Collator} handles un-normalized
+ * text properly, producing the same results as if the text were normalized in
+ * NFD. If canonical decomposition is turned off, it is the user's
+ * responsibility to ensure that all text is already in the appropriate form
+ * before performing a comparison or before getting a {@link CollationKey}.
+ * <p>
+ * <em>Examples:</em>
+ * <blockquote>
+ *
+ * <pre>
+ * // Get the Collator for US English and set its strength to PRIMARY
+ * Collator usCollator = Collator.getInstance(Locale.US);
+ * usCollator.setStrength(Collator.PRIMARY);
+ * if (usCollator.compare("abc", "ABC") == 0) {
+ * System.out.println("Strings are equivalent");
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * The following example shows how to compare two strings using the collator for
+ * the default locale.
+ * <blockquote>
+ *
+ * <pre>
+ * // Compare two strings in the default locale
+ * Collator myCollator = Collator.getInstance();
+ * myCollator.setDecomposition(Collator.NO_DECOMPOSITION);
+ * if (myCollator.compare("\u00e0\u0325", "a\u0325\u0300") != 0) {
+ * System.out.println("\u00e0\u0325 is not equal to a\u0325\u0300 without decomposition");
+ * myCollator.setDecomposition(Collator.CANONICAL_DECOMPOSITION);
+ * if (myCollator.compare("\u00e0\u0325", "a\u0325\u0300") != 0) {
+ * System.out.println("Error: \u00e0\u0325 should be equal to a\u0325\u0300 with decomposition");
+ * } else {
+ * System.out.println("\u00e0\u0325 is equal to a\u0325\u0300 with decomposition");
+ * }
+ * } else {
+ * System.out.println("Error: \u00e0\u0325 should be not equal to a\u0325\u0300 without decomposition");
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ *
+ * @see RuleBasedCollator
+ * @see CollationKey
*/
public abstract class Collator implements Comparator<Object>, Cloneable {
@@ -48,7 +129,8 @@
public static final int CANONICAL_DECOMPOSITION = 1;
/**
- * Constant used to specify the decomposition rule.
+ * Constant used to specify the decomposition rule. This value for
+ * decomposition is not supported.
*/
public static final int FULL_DECOMPOSITION = 2;
@@ -99,17 +181,17 @@
}
/**
- * Constructs a new instance of this Collator.
+ * Constructs a new {@code Collator} instance.
*/
protected Collator() {
super();
}
/**
- * Answers a new Collator with the same decomposition rule and strength
- * value as this Collator.
+ * Returns a new collator with the same decomposition mode and
+ * strength value as this collator.
*
- * @return a shallow copy of this Collator
+ * @return a shallow copy of this collator.
* @see java.lang.Cloneable
*/
@Override
@@ -124,45 +206,45 @@
}
/**
- * Compares the two objects to determine their relative ordering. The
- * objects must be Strings.
+ * Compares two objects to determine their relative order. The objects must
+ * be strings.
*
* @param object1
- * the first String to compare
+ * the first string to compare.
* @param object2
- * the second String to compare
- * @return an int < 0 if object1 is less than object2, 0 if they are equal,
- * and > 0 if object1 is greater than object2
- *
- * @exception ClassCastException
- * when the objects are not Strings
+ * the second string to compare.
+ * @return a negative value if {@code object1} is less than {@code object2},
+ * 0 if they are equal, and a positive value if {@code object1} is
+ * greater than {@code object2}.
+ * @throws ClassCastException
+ * if {@code object1} or {@code object2} is not a {@code String}.
*/
public int compare(Object object1, Object object2) {
return compare((String) object1, (String) object2);
}
/**
- * Compares the two Strings to determine their relative ordering.
+ * Compares two strings to determine their relative order.
*
* @param string1
- * the first String to compare
+ * the first string to compare.
* @param string2
- * the second String to compare
- * @return an int < 0 if string1 is less than string2, 0 if they are equal,
- * and > 0 if string1 is greater than string2
+ * the second string to compare.
+ * @return a negative value if {@code string1} is less than {@code string2},
+ * 0 if they are equal and a positive value if {@code string1} is
+ * greater than {@code string2}.
*/
public abstract int compare(String string1, String string2);
/**
- * Compares the specified object to this Collator and answer if they are
- * equal. The object must be an instance of Collator and have the same
- * strength and decomposition values.
+ * Compares this collator 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 Collator, false
- * otherwise
- *
+ * the object to compare with this object.
+ * @return {@code true} if {@code object} is a {@code Collator} object and
+ * it has the same strength and decomposition values as this
+ * collator; {@code false} otherwise.
* @see #hashCode
*/
@Override
@@ -176,65 +258,68 @@
}
/**
- * Compares the two Strings using the collation rules to determine if they
- * are equal.
+ * Compares two strings using the collation rules to determine if they are
+ * equal.
*
* @param string1
- * the first String to compare
+ * the first string to compare.
* @param string2
- * the second String to compare
- * @return true if the strings are equal using the collation rules, false
- * otherwise
+ * the second string to compare.
+ * @return {@code true} if {@code string1} and {@code string2} are equal
+ * using the collation rules, false otherwise.
*/
public boolean equals(String string1, String string2) {
return compare(string1, string2) == 0;
}
/**
- * Gets the list of installed Locales which support Collator.
+ * Gets the list of installed {@link java.util.Locale} objects which support
+ * {@code Collator}.
*
- * @return an array of Locale
+ * @return an array of {@code Locale}.
*/
public static Locale[] getAvailableLocales() {
return com.ibm.icu.text.Collator.getAvailableLocales();
}
/**
- * Answers a CollationKey for the specified String for this Collator with
- * the current decomposition rule and strength value.
+ * Returns a {@link CollationKey} for the specified string for this collator
+ * with the current decomposition rule and strength value.
*
* @param string
- * the collation key.
- * @return a CollationKey
+ * the source string that is converted into a collation key.
+ * @return the collation key for {@code string}.
*/
public abstract CollationKey getCollationKey(String string);
/**
- * Answers the decomposition rule for this Collator.
+ * Returns the decomposition rule for this collator.
*
- * @return the decomposition rule, either NO_DECOMPOSITION,
- * CANONICAL_DECOMPOSITION or FULL_DECOMPOSITION
+ * @return the decomposition rule, either {@code NO_DECOMPOSITION} or
+ * {@code CANONICAL_DECOMPOSITION}. {@code FULL_DECOMPOSITION} is
+ * not supported.
*/
public int getDecomposition() {
return decompositionMode_ICU_Java(this.icuColl.getDecomposition());
}
/**
- * Answers a Collator instance which is appropriate for the default Locale.
+ * Returns a {@code Collator} instance which is appropriate for the default
+ * {@code Locale}.
*
- * @return a Collator
+ * @return the collator for the default locale.
*/
public static Collator getInstance() {
return getInstance(Locale.getDefault());
}
/**
- * Answers a Collator instance which is appropriate for the specified
- * Locale.
+ * Returns a {@code Collator} instance which is appropriate for the
+ * specified {@code Locale}.
*
* @param locale
- * the Locale
- * @return a Collator
+ * the locale.
+ * @return the collator for {@code locale}.
*/
public static Collator getInstance(Locale locale) {
String key = locale.toString();
@@ -249,20 +334,19 @@
}
/**
- * Answers the strength value for this Collator.
+ * Returns the strength value for this collator.
*
- * @return the strength value, either PRIMARY, SECONDARY, TERTIARY, or
- * IDENTICAL
+ * @return the strength value, either PRIMARY, SECONDARY, TERTIARY or
+ * IDENTICAL.
*/
public int getStrength() {
return strength_ICU_Java(this.icuColl.getStrength());
}
/**
- * Answers an integer hash code for the receiver. Objects which are equal
- * answer the same value for this method.
+ * Returns an integer hash code for this collator.
*
- * @return the receiver's hash
+ * @return this collator's hash code.
*
* @see #equals(Object)
* @see #equals(String, String)
@@ -271,28 +355,28 @@
public abstract int hashCode();
/**
- * Sets the decomposition rule for this Collator.
+ * Sets the decomposition rule for this collator.
*
* @param value
- * the decomposition rule, either NO_DECOMPOSITION,
- * CANONICAL_DECOMPOSITION or FULL_DECOMPOSITION
- *
- * @exception IllegalArgumentException
- * when the decomposition rule is not valid
+ * the decomposition rule, either {@code NO_DECOMPOSITION} or
+ * {@code CANONICAL_DECOMPOSITION}. {@code FULL_DECOMPOSITION}
+ * is not supported.
+ * @throws IllegalArgumentException
+ * if the provided decomposition rule is not valid. This includes
+ * {@code FULL_DECOMPOSITION}.
*/
public void setDecomposition(int value) {
this.icuColl.setDecomposition(decompositionMode_Java_ICU(value));
}
/**
- * Sets the strength value for this Collator.
+ * Sets the strength value for this collator.
*
* @param value
* the strength value, either PRIMARY, SECONDARY, TERTIARY, or
- * IDENTICAL
- *
- * @exception IllegalArgumentException
- * when the strength value is not valid
+ * IDENTICAL.
+ * @throws IllegalArgumentException
+ * if the provided strength value is not valid.
*/
public void setStrength(int value) {
this.icuColl.setStrength(strength_Java_ICU(value));
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormat.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormat.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormat.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormat.java Thu May 7 08:42:00 2009
@@ -27,143 +27,270 @@
import org.apache.harmony.text.internal.nls.Messages;
/**
- * DateFormat is the abstract superclass of formats which format and parse
- * Dates.
+ * An abstract class for date/time formatting subclasses which formats and
+ * parses dates or time in a language-independent manner. The date/time
+ * formatting subclass, such as {@link SimpleDateFormat}, allows for formatting
+ * (i.e., date -> text), parsing (text -> date), and normalization. The date is
+ * represented as a {@code Date} object or as the milliseconds since January 1,
+ * 1970, 00:00:00 GMT.
+ * <p>
+ * DateFormat provides many class methods for obtaining default date/time
+ * formatters based on the default or a given locale and a number of formatting
+ * styles. The formatting styles include FULL, LONG, MEDIUM, and SHORT. More
+ * details and examples for using these styles are provided in the method
+ * descriptions.
+ * <p>
+ * {@code DateFormat} helps you to format and parse dates for any locale. Your
+ * code can be completely independent of the locale conventions for months, days
+ * of the week, or even the calendar format: lunar vs. solar.
+ * <p>
+ * To format a date for the current Locale, use one of the static factory
+ * methods:
+ * <blockquote>
+ *
+ * <pre>
+ * myString = DateFormat.getDateInstance().format(myDate);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * If you are formatting multiple dates, it is more efficient to get the format
+ * and use it multiple times so that the system doesn't have to fetch the
+ * information about the local language and country conventions multiple times.
+ * <blockquote>
+ *
+ * <pre>
+ * DateFormat df = DateFormat.getDateInstance();
+ * for (int i = 0; i < a.length; ++i) {
+ * output.println(df.format(myDate[i]) + "; ");
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * To format a number for a different locale, specify it in the call to
+ * {@code getDateInstance}:
+ * <blockquote>
+ *
+ * <pre>
+ * DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * {@code DateFormat} can also be used to parse strings:
+ * <blockquote>
+ *
+ * <pre>
+ * myDate = df.parse(myString);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Use {@code getDateInstance} to get the normal date format for a country.
+ * Other static factory methods are available: Use {@code getTimeInstance} to
+ * get the time format for a country. Use {@code getDateTimeInstance} to get the
+ * date and time format. You can pass in different options to these factory
+ * methods to control the length of the result; from SHORT to MEDIUM to LONG to
+ * FULL. The exact result depends on the locale, but generally:
+ * <ul>
+ * <li>SHORT is completely numeric, such as 12.13.52 or 3:30pm
+ * <li>MEDIUM is longer, such as Jan 12, 1952
+ * <li>LONG is longer, such as January 12, 1952 or 3:30:32pm
+ * <li>FULL is pretty completely specified, such as Tuesday, April 12, 1952 AD
+ * or 3:30:42pm PST.
+ * </ul>
+ * <p>
+ * If needed, the time zone can be set on the format. For even greater control
+ * over the formatting or parsing, try casting the {@code DateFormat} you get
+ * from the factory methods to a {@code SimpleDateFormat}. This will work for
+ * the majority of countries; just remember to put it in a try block in case you
+ * encounter an unusual one.
+ * <p>
+ * There are versions of the parse and format methods which use
+ * {@code ParsePosition} and {@code FieldPosition} to allow you to
+ * <ul>
+ * <li>progressively parse through pieces of a string;
+ * <li>align any particular field.
+ * </ul>
+ * <h4>Synchronization</h4>
+ * <p>
+ * 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 NumberFormat
+ * @see SimpleDateFormat
+ * @see Calendar
+ * @see TimeZone
*/
public abstract class DateFormat extends Format {
private static final long serialVersionUID = 7218322306649953788L;
+ /**
+ * The calendar that this {@code DateFormat} uses to format a number
+ * representing a date.
+ */
protected Calendar calendar;
+ /**
+ * The number format used to format a number.
+ */
protected NumberFormat numberFormat;
/**
- * Format style constant.
+ * The format style constant defining the default format style. The default
+ * is MEDIUM.
*/
public final static int DEFAULT = 2;
/**
- * Format style constant.
+ * The format style constant defining the full style.
*/
public final static int FULL = 0;
/**
- * Format style constant.
+ * The format style constant defining the long style.
*/
public final static int LONG = 1;
/**
- * Format style constant.
+ * The format style constant defining the medium style.
*/
public final static int MEDIUM = 2;
/**
- * Format style constant.
+ * The format style constant defining the short style.
*/
public final static int SHORT = 3;
/**
- * Field constant.
+ * The {@code FieldPosition} selector for 'G' field alignment, corresponds
+ * to the {@link Calendar#ERA} field.
*/
public final static int ERA_FIELD = 0;
/**
- * Field constant.
+ * The {@code FieldPosition} selector for 'y' field alignment, corresponds
+ * to the {@link Calendar#YEAR} field.
*/
public final static int YEAR_FIELD = 1;
/**
- * Field constant.
+ * The {@code FieldPosition} selector for 'M' field alignment, corresponds
+ * to the {@link Calendar#MONTH} field.
*/
public final static int MONTH_FIELD = 2;
/**
- * Field constant.
+ * The {@code FieldPosition} selector for 'd' field alignment, corresponds
+ * to the {@link Calendar#DATE} field.
*/
public final static int DATE_FIELD = 3;
/**
- * Field constant.
+ * The {@code FieldPosition} selector for 'k' field alignment, corresponds
+ * to the {@link Calendar#HOUR_OF_DAY} field. {@code HOUR_OF_DAY1_FIELD} is
+ * used for the one-based 24-hour clock. For example, 23:59 + 01:00 results
+ * in 24:59.
*/
public final static int HOUR_OF_DAY1_FIELD = 4;
/**
- * Field constant.
+ * The {@code FieldPosition} selector for 'H' field alignment, corresponds
+ * to the {@link Calendar#HOUR_OF_DAY} field. {@code HOUR_OF_DAY0_FIELD} is
+ * used for the zero-based 24-hour clock. For example, 23:59 + 01:00 results
+ * in 00:59.
*/
public final static int HOUR_OF_DAY0_FIELD = 5;
/**
- * Field constant.
+ * FieldPosition selector for 'm' field alignment, corresponds to the
+ * {@link Calendar#MINUTE} field.
*/
public final static int MINUTE_FIELD = 6;
/**
- * Field constant.
+ * FieldPosition selector for 's' field alignment, corresponds to the
+ * {@link Calendar#SECOND} field.
*/
public final static int SECOND_FIELD = 7;
/**
- * Field constant.
+ * FieldPosition selector for 'S' field alignment, corresponds to the
+ * {@link Calendar#MILLISECOND} field.
*/
public final static int MILLISECOND_FIELD = 8;
/**
- * Field constant.
+ * FieldPosition selector for 'E' field alignment, corresponds to the
+ * {@link Calendar#DAY_OF_WEEK} field.
*/
public final static int DAY_OF_WEEK_FIELD = 9;
/**
- * Field constant.
+ * FieldPosition selector for 'D' field alignment, corresponds to the
+ * {@link Calendar#DAY_OF_YEAR} field.
*/
public final static int DAY_OF_YEAR_FIELD = 10;
/**
- * Field constant.
+ * FieldPosition selector for 'F' field alignment, corresponds to the
+ * {@link Calendar#DAY_OF_WEEK_IN_MONTH} field.
*/
public final static int DAY_OF_WEEK_IN_MONTH_FIELD = 11;
/**
- * Field constant.
+ * FieldPosition selector for 'w' field alignment, corresponds to the
+ * {@link Calendar#WEEK_OF_YEAR} field.
*/
public final static int WEEK_OF_YEAR_FIELD = 12;
/**
- * Field constant.
+ * FieldPosition selector for 'W' field alignment, corresponds to the
+ * {@link Calendar#WEEK_OF_MONTH} field.
*/
public final static int WEEK_OF_MONTH_FIELD = 13;
/**
- * Field constant.
+ * FieldPosition selector for 'a' field alignment, corresponds to the
+ * {@link Calendar#AM_PM} field.
*/
public final static int AM_PM_FIELD = 14;
/**
- * Field constant.
+ * FieldPosition selector for 'h' field alignment, corresponding to the
+ * {@link Calendar#HOUR} field. {@code HOUR1_FIELD} is used for the
+ * one-based 12-hour clock. For example, 11:30 PM + 1 hour results in 12:30
+ * AM.
*/
public final static int HOUR1_FIELD = 15;
/**
- * Field constant.
+ * The {@code FieldPosition} selector for 'z' field alignment, corresponds
+ * to the {@link Calendar#ZONE_OFFSET} and {@link Calendar#DST_OFFSET}
+ * fields.
*/
public final static int HOUR0_FIELD = 16;
/**
- * Field constant.
+ * The {@code FieldPosition} selector for 'z' field alignment, corresponds
+ * to the {@link Calendar#ZONE_OFFSET} and {@link Calendar#DST_OFFSET}
+ * fields.
*/
public final static int TIMEZONE_FIELD = 17;
/**
- * Constructs a new instance of DateFormat.
- *
+ * Constructs a new instance of {@code DateFormat}.
*/
protected DateFormat() {
}
/**
- * Answers a new instance of DateFormat with the same properties.
+ * Returns a new instance of {@code DateFormat} with the same properties.
*
- * @return a shallow copy of this DateFormat
+ * @return a shallow copy of this {@code DateFormat}.
*
* @see java.lang.Cloneable
*/
@@ -176,15 +303,14 @@
}
/**
- * Compares the specified object to this DateFormat and answer if they are
- * equal. The object must be an instance of DateFormat with the same
- * properties.
+ * Compares this date format 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 DateFormat, false
- * otherwise
- *
+ * the object to compare with this date format.
+ * @return {@code true} if {@code object} is a {@code DateFormat} object and
+ * it has the same properties as this date format; {@code false}
+ * otherwise.
* @see #hashCode
*/
@Override
@@ -207,23 +333,27 @@
}
/**
- * Formats the specified object into the specified StringBuffer using the
- * rules of this DateFormat. 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 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 object
- * the object to format, must be a Date or a Number. If the
- * object is a Number, a Date is constructed using the
- * <code>longValue()</code> of the Number.
+ * the source object to format, must be a {@code Date} or a
+ * {@code Number}. If {@code object} is a number then a date is
+ * constructed using the {@code longValue()} of the number.
* @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 the object is not a Date or a Number
+ * 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 {@code object} is neither a {@code Date} nor a
+ * {@code Number} instance.
*/
@Override
public final StringBuffer format(Object object, StringBuffer buffer,
@@ -239,11 +369,11 @@
}
/**
- * Formats the specified Date using the rules of this DateFormat.
+ * Formats the specified date using the rules of this date format.
*
* @param date
- * the Date to format
- * @return the formatted String
+ * the date to format.
+ * @return the formatted string.
*/
public final String format(Date date) {
return format(date, new StringBuffer(), new FieldPosition(0))
@@ -251,57 +381,65 @@
}
/**
- * Formats the specified Date into the specified StringBuffer using the
- * rules of this DateFormat. 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>
+ * on input: an optional alignment field; on output: the offsets
+ * of the alignment field in the formatted text.
+ * @return the string buffer.
*/
public abstract StringBuffer format(Date date, StringBuffer buffer,
FieldPosition field);
/**
- * Gets the list of installed Locales which support DateFormat.
+ * Gets the list of installed locales which support {@code DateFormat}.
*
- * @return an array of Locale
+ * @return an array of locales.
*/
public static Locale[] getAvailableLocales() {
return Locale.getAvailableLocales();
}
/**
- * Answers the Calendar used by this DateFormat.
+ * Returns the calendar used by this {@code DateFormat}.
*
- * @return a Calendar
+ * @return the calendar used by this date format.
*/
public Calendar getCalendar() {
return calendar;
}
/**
- * Answers a DateFormat instance for formatting and parsing dates in the
- * DEFAULT style for the default Locale.
+ * Returns a {@code DateFormat} instance for formatting and parsing dates in
+ * the DEFAULT style for the default locale.
*
- * @return a DateFormat
+ * @return the {@code DateFormat} instance for the default style and locale.
*/
public final static DateFormat getDateInstance() {
return getDateInstance(DEFAULT);
}
/**
- * Answers a DateFormat instance for formatting and parsing dates in the
- * specified style for the default Locale.
+ * Returns a {@code DateFormat} instance for formatting and parsing dates in
+ * the specified style for the default locale.
*
* @param style
- * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
- * @return a DateFormat
+ * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
+ * @return the {@code DateFormat} instance for {@code style} and the default
+ * locale.
+ * @throws IllegalArgumentException
+ * if {@code style} is not one of SHORT, MEDIUM, LONG, FULL, or
+ * DEFAULT.
*/
public final static DateFormat getDateInstance(int style) {
checkDateStyle(style);
@@ -309,14 +447,18 @@
}
/**
- * Answers a DateFormat instance for formatting and parsing dates in the
- * specified style for the specified Locale.
+ * Returns a {@code DateFormat} instance for formatting and parsing dates in
+ * the specified style for the specified locale.
*
* @param style
- * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
+ * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
* @param locale
- * the Locale
- * @return a DateFormat
+ * the locale.
+ * @throws IllegalArgumentException
+ * if {@code style} is not one of SHORT, MEDIUM, LONG, FULL, or
+ * DEFAULT.
+ * @return the {@code DateFormat} instance for {@code style} and
+ * {@code locale}.
*/
public final static DateFormat getDateInstance(int style, Locale locale) {
checkDateStyle(style);
@@ -325,25 +467,28 @@
}
/**
- * Answers a DateFormat instance for formatting and parsing dates and times
- * in the DEFAULT style for the default Locale.
+ * Returns a {@code DateFormat} instance for formatting and parsing dates
+ * and time values in the DEFAULT style for the default locale.
*
- * @return a DateFormat
+ * @return the {@code DateFormat} instance for the default style and locale.
*/
public final static DateFormat getDateTimeInstance() {
return getDateTimeInstance(DEFAULT, DEFAULT);
}
/**
- * Answers a <code>DateFormat</code> instance for the formatting and
- * parsing of both dates and times in the manner appropriate to the default
- * Locale.
+ * Returns a {@code DateFormat} instance for formatting and parsing of both
+ * dates and time values in the manner appropriate for the default locale.
*
* @param dateStyle
- * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
+ * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
* @param timeStyle
- * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
- * @return a DateFormat
+ * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
+ * @return the {@code DateFormat} instance for {@code dateStyle},
+ * {@code timeStyle} and the default locale.
+ * @throws IllegalArgumentException
+ * if {@code dateStyle} or {@code timeStyle} is not one of
+ * SHORT, MEDIUM, LONG, FULL, or DEFAULT.
*/
public final static DateFormat getDateTimeInstance(int dateStyle,
int timeStyle) {
@@ -353,16 +498,20 @@
}
/**
- * Answers a DateFormat instance for formatting and parsing dates and times
- * in the specified styles for the specified Locale.
+ * Returns a {@code DateFormat} instance for formatting and parsing dates
+ * and time values in the specified styles for the specified locale.
*
* @param dateStyle
- * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
+ * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
* @param timeStyle
- * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
+ * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
* @param locale
- * the Locale
- * @return a DateFormat
+ * the locale.
+ * @return the {@code DateFormat} instance for {@code dateStyle},
+ * {@code timeStyle} and {@code locale}.
+ * @throws IllegalArgumentException
+ * if {@code dateStyle} or {@code timeStyle} is not one of
+ * SHORT, MEDIUM, LONG, FULL, or DEFAULT.
*/
public final static DateFormat getDateTimeInstance(int dateStyle,
int timeStyle, Locale locale) {
@@ -373,19 +522,20 @@
}
/**
- * Answers a DateFormat instance for formatting and parsing dates and times
- * in the SHORT style for the default Locale.
+ * Returns a {@code DateFormat} instance for formatting and parsing dates
+ * and times in the SHORT style for the default locale.
*
- * @return a DateFormat
+ * @return the {@code DateFormat} instance for the SHORT style and default
+ * locale.
*/
public final static DateFormat getInstance() {
return getDateTimeInstance(SHORT, SHORT);
}
/**
- * Answers the NumberFormat used by this DateFormat.
+ * Returns the {@code NumberFormat} used by this {@code DateFormat}.
*
- * @return a NumberFormat
+ * @return the {@code NumberFormat} used by this date format.
*/
public NumberFormat getNumberFormat() {
return numberFormat;
@@ -413,22 +563,26 @@
}
/**
- * Answers a DateFormat instance for formatting and parsing times in the
- * DEFAULT style for the default Locale.
+ * Returns a {@code DateFormat} instance for formatting and parsing time
+ * values in the DEFAULT style for the default locale.
*
- * @return a DateFormat
+ * @return the {@code DateFormat} instance for the default style and locale.
*/
public final static DateFormat getTimeInstance() {
return getTimeInstance(DEFAULT);
}
/**
- * Answers a DateFormat instance for formatting and parsing times in the
- * specified style for the default Locale.
+ * Returns a {@code DateFormat} instance for formatting and parsing time
+ * values in the specified style for the default locale.
*
* @param style
- * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
- * @return a DateFormat
+ * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
+ * @return the {@code DateFormat} instance for {@code style} and the default
+ * locale.
+ * @throws IllegalArgumentException
+ * if {@code style} is not one of SHORT, MEDIUM, LONG, FULL, or
+ * DEFAULT.
*/
public final static DateFormat getTimeInstance(int style) {
checkTimeStyle(style);
@@ -436,14 +590,18 @@
}
/**
- * Answers a DateFormat instance for formatting and parsing times in the
- * specified style for the specified Locale.
+ * Returns a {@code DateFormat} instance for formatting and parsing time
+ * values in the specified style for the specified locale.
*
* @param style
- * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
+ * one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
* @param locale
- * the Locale
- * @return a DateFormat
+ * the locale.
+ * @throws IllegalArgumentException
+ * if {@code style} is not one of SHORT, MEDIUM, LONG, FULL, or
+ * DEFAULT.
+ * @return the {@code DateFormat} instance for {@code style} and
+ * {@code locale}.
*/
public final static DateFormat getTimeInstance(int style, Locale locale) {
checkTimeStyle(style);
@@ -452,22 +610,14 @@
}
/**
- * Answers the TimeZone of the Calendar used by this DateFormat.
+ * Returns the time zone of this date format's calendar.
*
- * @return a TimeZone
+ * @return the time zone of the calendar used by this date format.
*/
public TimeZone getTimeZone() {
return calendar.getTimeZone();
}
- /**
- * 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 calendar.getFirstDayOfWeek()
@@ -478,24 +628,23 @@
}
/**
- * Answers if the Calendar used by this DateFormat is lenient.
+ * Indicates whether the calendar used by this date format is lenient.
*
- * @return true when the Calendar is lenient, false otherwise
+ * @return {@code true} if the calendar is lenient; {@code false} otherwise.
*/
public boolean isLenient() {
return calendar.isLenient();
}
/**
- * Parse a Date from the specified String using the rules of this
- * DateFormat.
+ * Parses a date from the specified string using the rules of this date
+ * format.
*
* @param string
- * the String to parse
- * @return the Date resulting from the parse
- *
- * @exception ParseException
- * when an error occurs during parsing
+ * the string to parse.
+ * @return the {@code Date} resulting from the parsing.
+ * @throws ParseException
+ * if an error occurs during parsing.
*/
public Date parse(String string) throws ParseException {
ParsePosition position = new ParsePosition(0);
@@ -509,32 +658,52 @@
}
/**
- * 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.
+ * <p>
+ * By default, parsing is lenient: If the input is not in the form used by
+ * this object's format method but can still be parsed as a date, then the
+ * parse succeeds. Clients may insist on strict adherence to the format by
+ * calling {@code setLenient(false)}.
+ *
* @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 the Date resulting from the parse, or null if there is an error
+ * 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.
*/
public abstract Date parse(String string, ParsePosition position);
/**
- * 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.
+ * <p>
+ * By default, parsing is lenient: If the input is not in the form used by
+ * this object's format method but can still be parsed as a date, then the
+ * parse succeeds. Clients may insist on strict adherence to the format by
+ * calling {@code setLenient(false)}.
+ *
* @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 the Date resulting from the parse, or null if there is an error
+ * 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 parsing, or {@code null} if there is
+ * an error.
*/
@Override
public Object parseObject(String string, ParsePosition position) {
@@ -542,40 +711,44 @@
}
/**
- * Sets the Calendar used by this DateFormat.
+ * Sets the calendar used by this date format.
*
* @param cal
- * the Calendar
+ * the new calendar.
*/
public void setCalendar(Calendar cal) {
calendar = cal;
}
/**
- * Sets if the Calendar used by this DateFormat is lenient.
+ * Specifies whether or not date/time parsing shall be lenient. With lenient
+ * parsing, the parser may use heuristics to interpret inputs that do not
+ * precisely match this object's format. With strict parsing, inputs must
+ * match this object's format.
*
* @param value
- * true to set the Calendar to be lenient, false otherwise
+ * {@code true} to set the calendar to be lenient, {@code false}
+ * otherwise.
*/
public void setLenient(boolean value) {
calendar.setLenient(value);
}
/**
- * Sets the NumberFormat used by this DateFormat.
+ * Sets the {@code NumberFormat} used by this date format.
*
* @param format
- * the NumberFormat
+ * the new number format.
*/
public void setNumberFormat(NumberFormat format) {
numberFormat = format;
}
/**
- * Sets the TimeZone of the Calendar used by this DateFormat.
+ * Sets the time zone of the calendar used by this date format.
*
* @param timezone
- * the TimeZone
+ * the new time zone.
*/
public void setTimeZone(TimeZone timezone) {
calendar.setTimeZone(timezone);
@@ -583,12 +756,11 @@
/**
* The instances of this inner class are used as attribute keys and values
- * in AttributedCharacterIterator that
- * SimpleDateFormat.formatToCharacterIterator() method returns.
+ * in {@code AttributedCharacterIterator} that the
+ * {@link SimpleDateFormat#formatToCharacterIterator(Object)} method returns.
* <p>
- * There is no public constructor to this class, the only instances are the
+ * There is no public constructor in this class, the only instances are the
* constants defined here.
- * <p>
*/
public static class Field extends Format.Field {
@@ -596,58 +768,117 @@
private static Hashtable<Integer, Field> table = new Hashtable<Integer, Field>();
+ /**
+ * Marks the era part of a date.
+ */
public final static Field ERA = new Field("era", Calendar.ERA); //$NON-NLS-1$
+ /**
+ * Marks the year part of a date.
+ */
public final static Field YEAR = new Field("year", Calendar.YEAR); //$NON-NLS-1$
+ /**
+ * Marks the month part of a date.
+ */
public final static Field MONTH = new Field("month", Calendar.MONTH); //$NON-NLS-1$
+ /**
+ * Marks the hour of the day part of a date (0-11).
+ */
public final static Field HOUR_OF_DAY0 = new Field("hour of day", //$NON-NLS-1$
Calendar.HOUR_OF_DAY);
+ /**
+ * Marks the hour of the day part of a date (1-12).
+ */
public final static Field HOUR_OF_DAY1 = new Field("hour of day 1", -1); //$NON-NLS-1$
+ /**
+ * Marks the minute part of a time.
+ */
public final static Field MINUTE = new Field("minute", Calendar.MINUTE); //$NON-NLS-1$
+ /**
+ * Marks the second part of a time.
+ */
public final static Field SECOND = new Field("second", Calendar.SECOND); //$NON-NLS-1$
+ /**
+ * Marks the millisecond part of a time.
+ */
public final static Field MILLISECOND = new Field("millisecond", //$NON-NLS-1$
Calendar.MILLISECOND);
+ /**
+ * Marks the day of the week part of a date.
+ */
public final static Field DAY_OF_WEEK = new Field("day of week", //$NON-NLS-1$
Calendar.DAY_OF_WEEK);
+ /**
+ * Marks the day of the month part of a date.
+ */
public final static Field DAY_OF_MONTH = new Field("day of month", //$NON-NLS-1$
Calendar.DAY_OF_MONTH);
+ /**
+ * Marks the day of the year part of a date.
+ */
public final static Field DAY_OF_YEAR = new Field("day of year", //$NON-NLS-1$
Calendar.DAY_OF_YEAR);
+ /**
+ * Marks the day of the week in the month part of a date.
+ */
public final static Field DAY_OF_WEEK_IN_MONTH = new Field(
"day of week in month", Calendar.DAY_OF_WEEK_IN_MONTH); //$NON-NLS-1$
+ /**
+ * Marks the week of the year part of a date.
+ */
public final static Field WEEK_OF_YEAR = new Field("week of year", //$NON-NLS-1$
Calendar.WEEK_OF_YEAR);
+ /**
+ * Marks the week of the month part of a date.
+ */
public final static Field WEEK_OF_MONTH = new Field("week of month", //$NON-NLS-1$
Calendar.WEEK_OF_MONTH);
+ /**
+ * Marks the time indicator part of a date.
+ */
public final static Field AM_PM = new Field("am pm", Calendar.AM_PM); //$NON-NLS-1$
+ /**
+ * Marks the hour part of a date (0-11).
+ */
public final static Field HOUR0 = new Field("hour", Calendar.HOUR); //$NON-NLS-1$
+ /**
+ * Marks the hour part of a date (1-12).
+ */
public final static Field HOUR1 = new Field("hour 1", -1); //$NON-NLS-1$
+ /**
+ * Marks the time zone part of a date.
+ */
public final static Field TIME_ZONE = new Field("time zone", -1); //$NON-NLS-1$
/**
- * The Calendar field that this Field represents.
+ * The calendar field that this field represents.
*/
private int calendarField = -1;
/**
- * Constructs a new instance of DateFormat.Field with the given
+ * Constructs a new instance of {@code DateFormat.Field} with the given
* fieldName and calendar field.
+ *
+ * @param fieldName
+ * the field name.
+ * @param calendarField
+ * the calendar field type of the field.
*/
protected Field(String fieldName, int calendarField) {
super(fieldName);
@@ -659,20 +890,25 @@
}
/**
- * Answers the Calendar field this Field represents
+ * Returns the Calendar field that this field represents.
*
- * @return int calendar field
+ * @return the calendar field.
*/
public int getCalendarField() {
return calendarField;
}
/**
- * Answers the DateFormat.Field instance for the given calendar field
+ * Returns the {@code DateFormat.Field} instance for the given calendar
+ * field.
*
* @param calendarField
- * a calendar field constant
- * @return null if there is no Field for this calendar field
+ * a calendar field constant.
+ * @return the {@code DateFormat.Field} corresponding to
+ * {@code calendarField}.
+ * @throws IllegalArgumentException
+ * if {@code calendarField} is negative or greater than the
+ * field count of {@code Calendar}.
*/
public static Field ofCalendarField(int calendarField) {
if (calendarField < 0 || calendarField >= Calendar.FIELD_COUNT) {
@@ -683,8 +919,12 @@
}
/**
- * Serialization method resolve instances to the constant
- * DateFormat.Field values
+ * Resolves instances that are deserialized to the constant
+ * {@code DateFormat.Field} values.
+ *
+ * @return the resolved field object.
+ * @throws InvalidObjectException
+ * if an error occurs while resolving the field object.
*/
@Override
protected Object readResolve() throws InvalidObjectException {