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 [1/5] -
/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/
Author: tellison
Date: Thu May 7 08:42:00 2009
New Revision: 772552
URL: http://svn.apache.org/viewvc?rev=772552&view=rev
Log:
Apply partial patch for HARMONY-6189 (Javadocs for java.text.*)
Modified:
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Annotation.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedCharacterIterator.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedString.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Bidi.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/BreakIterator.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CharacterIterator.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ChoiceFormat.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationElementIterator.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationKey.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Collator.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormat.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormatSymbols.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormat.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormatSymbols.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/FieldPosition.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Format.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/MessageFormat.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/NumberFormat.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParseException.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParsePosition.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/RuleBasedCollator.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/SimpleDateFormat.java
harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/StringCharacterIterator.java
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Annotation.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Annotation.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Annotation.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Annotation.java Thu May 7 08:42:00 2009
@@ -18,20 +18,50 @@
package java.text;
/**
- * Annotation
+ * Wrapper for a text attribute value which represents an annotation. An
+ * annotation has two special aspects:
+ * <ol>
+ * <li>it is connected to a range of main text; if this range or the main text
+ * is changed then the annotation becomes invalid,</li>
+ * <li>it can not be joined with adjacent annotations even if the text attribute
+ * value is the same.</li>
+ * </ol>
+ * <p>
+ * By wrapping text attribute values into an {@code Annotation}, these aspects
+ * will be taken into account when handling annotation text and the
+ * corresponding main text.
+ * <p>
+ * Note: There is no semantic connection between this annotation class and the
+ * {@code java.lang.annotation} package.
*/
public class Annotation {
private Object value;
+ /**
+ * Constructs a new {@code Annotation}.
+ *
+ * @param attribute the attribute attached to this annotation. This may be
+ * {@code null}.
+ */
public Annotation(Object attribute) {
value = attribute;
}
+ /**
+ * Returns the value of this annotation. The value may be {@code null}.
+ *
+ * @return the value of this annotation or {@code null}.
+ */
public Object getValue() {
return value;
}
+ /**
+ * Returns this annotation in string representation.
+ *
+ * @return the string representation of this annotation.
+ */
@Override
public String toString() {
return getClass().getName() + "[value=" + value + ']'; //$NON-NLS-1$
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedCharacterIterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedCharacterIterator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedCharacterIterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedCharacterIterator.java Thu May 7 08:42:00 2009
@@ -25,27 +25,68 @@
import org.apache.harmony.text.internal.nls.Messages;
/**
- * AttributedCharacterIterator
+ * Extends the
+ * {@link CharacterIterator} interface, adding support for iterating over
+ * attributes and not only characters. An
+ * {@code AttributedCharacterIterator} also allows the user to find runs and
+ * their limits. Runs are defined as ranges of characters that all have the same
+ * attributes with the same values.
*/
public interface AttributedCharacterIterator extends CharacterIterator {
+ /**
+ * Defines keys for text attributes.
+ */
public static class Attribute implements Serializable {
private static final long serialVersionUID = -9142742483513960612L;
+ /**
+ * This attribute marks segments from an input method. Most input
+ * methods create these segments for words.
+ *
+ * The value objects are of the type {@code Annotation} which contain
+ * {@code null}.
+ */
public static final Attribute INPUT_METHOD_SEGMENT = new Attribute(
"input_method_segment"); //$NON-NLS-1$
+ /**
+ * The attribute describing the language of a character. The value
+ * objects are of type {@code Locale} or a subtype of it.
+ */
public static final Attribute LANGUAGE = new Attribute("language"); //$NON-NLS-1$
+ /**
+ * For languages that have different reading directions of text (like
+ * Japanese), this attribute allows to define which reading should be
+ * used. The value objects are of type {@code Annotation} which
+ * contain a {@code String}.
+ */
public static final Attribute READING = new Attribute("reading"); //$NON-NLS-1$
private String name;
+ /**
+ * The constructor for an {@code Attribute} with the name passed.
+ *
+ * @param name
+ * the name of the new {@code Attribute}.
+ */
protected Attribute(String name) {
this.name = name;
}
+ /**
+ * Compares this attribute with the specified object. Checks if both
+ * objects are the same instance. It is defined final so all subclasses
+ * have the same behavior for this method.
+ *
+ * @param object
+ * the object to compare against.
+ * @return {@code true} if the object passed is equal to this instance;
+ * {@code false} otherwise.
+ */
@Override
public final boolean equals(Object object) {
if (object == null || !(object.getClass().equals(this.getClass()))) {
@@ -54,15 +95,35 @@
return name.equals(((Attribute) object).name);
}
+ /**
+ * Returns the name of this attribute.
+ *
+ * @return the name of this attribute.
+ */
protected String getName() {
return name;
}
+ /**
+ * Calculates the hash code for objects of type {@code Attribute}. It
+ * is defined final so all sub types calculate their hash code
+ * identically.
+ *
+ * @return the hash code for this instance of {@code Attribute}.
+ */
@Override
public final int hashCode() {
return name.hashCode();
}
+ /**
+ * Resolves a deserialized instance to the correct constant attribute.
+ *
+ * @return the {@code Attribute} this instance represents.
+ * @throws InvalidObjectException
+ * if this instance is not of type {@code Attribute.class}
+ * or if it is not a known {@code Attribute}.
+ */
protected Object readResolve() throws InvalidObjectException {
if (this.getClass() != Attribute.class) {
// text.0C=cannot resolve subclasses
@@ -81,27 +142,100 @@
throw new InvalidObjectException(Messages.getString("text.02")); //$NON-NLS-1$
}
+ /**
+ * Returns the name of the class followed by a "(", the name of the
+ * attribute, and a ")".
+ *
+ * @return the string representing this instance.
+ */
@Override
public String toString() {
return getClass().getName() + '(' + getName() + ')';
}
}
+ /**
+ * Returns a set of attributes present in the {@code
+ * AttributedCharacterIterator}. An empty set is returned if no attributes
+ * were defined.
+ *
+ * @return a set of attribute keys; may be empty.
+ */
public Set<Attribute> getAllAttributeKeys();
+ /**
+ * Returns the value stored in the attribute for the current character. If
+ * the attribute was not defined then {@code null} is returned.
+ *
+ * @param attribute the attribute for which the value should be returned.
+ * @return the value of the requested attribute for the current character or
+ * {@code null} if it was not defined.
+ */
public Object getAttribute(Attribute attribute);
+ /**
+ * Returns a map of all attributes of the current character. If no
+ * attributes were defined for the current character then an empty map is
+ * returned.
+ *
+ * @return a map of all attributes for the current character or an empty
+ * map.
+ */
public Map<Attribute, Object> getAttributes();
+ /**
+ * Returns the index of the last character in the run having the same
+ * attributes as the current character.
+ *
+ * @return the index of the last character of the current run.
+ */
public int getRunLimit();
+ /**
+ * Returns the index of the last character in the run that has the same
+ * attribute value for the given attribute as the current character.
+ *
+ * @param attribute
+ * the attribute which the run is based on.
+ * @return the index of the last character of the current run.
+ */
public int getRunLimit(Attribute attribute);
+ /**
+ * Returns the index of the last character in the run that has the same
+ * attribute values for the attributes in the set as the current character.
+ *
+ * @param attributes
+ * the set of attributes which the run is based on.
+ * @return the index of the last character of the current run.
+ */
public int getRunLimit(Set<? extends Attribute> attributes);
+ /**
+ * Returns the index of the first character in the run that has the same
+ * attributes as the current character.
+ *
+ * @return the index of the last character of the current run.
+ */
public int getRunStart();
+ /**
+ * Returns the index of the first character in the run that has the same
+ * attribute value for the given attribute as the current character.
+ *
+ * @param attribute
+ * the attribute which the run is based on.
+ * @return the index of the last character of the current run.
+ */
public int getRunStart(Attribute attribute);
+ /**
+ * Returns the index of the first character in the run that has the same
+ * attribute values for the attributes in the set as the current character.
+ *
+ * @param attributes
+ * the set of attributes which the run is based on.
+ * @return the index of the last character of the current run.
+ */
public int getRunStart(Set<? extends Attribute> attributes);
}
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedString.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedString.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedString.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedString.java Thu May 7 08:42:00 2009
@@ -31,7 +31,8 @@
import org.apache.harmony.text.internal.nls.Messages;
/**
- * AttributedString
+ * Holds a string with attributes describing the characters of
+ * this string.
*/
public class AttributedString {
@@ -89,11 +90,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 AttributedIterator} with the same source string,
+ * begin, end, and current index as this attributed iterator.
*
+ * @return a shallow copy of this attributed iterator.
* @see java.lang.Cloneable
*/
@Override
@@ -111,12 +111,6 @@
}
}
- /**
- * Answers the character at the current index in the source String.
- *
- * @return the current character, or DONE if the current index is past
- * the end
- */
public char current() {
if (offset == end) {
return DONE;
@@ -124,12 +118,6 @@
return attrString.text.charAt(offset);
}
- /**
- * Sets the current position to the begin index and answers the
- * character at the begin index.
- *
- * @return the character at the begin index
- */
public char first() {
if (begin == end) {
return DONE;
@@ -139,27 +127,27 @@
}
/**
- * 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 to iterate.
*/
public int getBeginIndex() {
return begin;
}
/**
- * 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 to iterate.
*/
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;
@@ -188,6 +176,12 @@
return false;
}
+ /**
+ * Returns a set of attributes present in the {@code AttributedString}.
+ * An empty set returned indicates that no attributes where defined.
+ *
+ * @return a set of attribute keys that may be empty.
+ */
public Set<AttributedIterator.Attribute> getAllAttributeKeys() {
if (begin == 0 && end == attrString.text.length()
&& attributesAllowed == null) {
@@ -350,12 +344,6 @@
return start;
}
- /**
- * Sets the current position to the end index - 1 and answers the
- * character at the current position.
- *
- * @return the character before the end index
- */
public char last() {
if (begin == end) {
return DONE;
@@ -364,13 +352,6 @@
return attrString.text.charAt(offset);
}
- /**
- * 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
- */
public char next() {
if (offset >= (end - 1)) {
offset = end;
@@ -379,13 +360,6 @@
return attrString.text.charAt(++offset);
}
- /**
- * 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
- */
public char previous() {
if (offset == begin) {
return DONE;
@@ -393,16 +367,6 @@
return attrString.text.charAt(--offset);
}
- /**
- * 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
- */
public char setIndex(int location) {
if (location < begin || location > end) {
throw new IllegalArgumentException();
@@ -415,6 +379,14 @@
}
}
+ /**
+ * Constructs an {@code AttributedString} from an {@code
+ * AttributedCharacterIterator}, which represents attributed text.
+ *
+ * @param iterator
+ * the {@code AttributedCharacterIterator} that contains the text
+ * for this attributed string.
+ */
public AttributedString(AttributedCharacterIterator iterator) {
if (iterator.getBeginIndex() > iterator.getEndIndex()) {
// text.0A=Invalid substring range
@@ -490,17 +462,63 @@
}
}
+ /**
+ * Constructs an {@code AttributedString} from a range of the text contained
+ * in the specified {@code AttributedCharacterIterator}, starting at {@code
+ * start} and ending at {@code end}. All attributes will be copied to this
+ * attributed string.
+ *
+ * @param iterator
+ * the {@code AttributedCharacterIterator} that contains the text
+ * for this attributed string.
+ * @param start
+ * the start index of the range of the copied text.
+ * @param end
+ * the end index of the range of the copied text.
+ * @throws IllegalArgumentException
+ * if {@code start} is less than first index of
+ * {@code iterator}, {@code end} is greater than the last
+ * index + 1 in {@code iterator} or if {@code start > end}.
+ */
public AttributedString(AttributedCharacterIterator iterator, int start,
int end) {
this(iterator, start, end, iterator.getAllAttributeKeys());
}
+ /**
+ * Constructs an {@code AttributedString} from a range of the text contained
+ * in the specified {@code AttributedCharacterIterator}, starting at {@code
+ * start}, ending at {@code end} and it will copy the attributes defined in
+ * the specified set. If the set is {@code null} then all attributes are
+ * copied.
+ *
+ * @param iterator
+ * the {@code AttributedCharacterIterator} that contains the text
+ * for this attributed string.
+ * @param start
+ * the start index of the range of the copied text.
+ * @param end
+ * the end index of the range of the copied text.
+ * @param attributes
+ * the set of attributes that will be copied, or all if it is
+ * {@code null}.
+ * @throws IllegalArgumentException
+ * if {@code start} is less than first index of
+ * {@code iterator}, {@code end} is greater than the last index +
+ * 1 in {@code iterator} or if {@code start > end}.
+ */
public AttributedString(AttributedCharacterIterator iterator, int start,
int end, AttributedCharacterIterator.Attribute[] attributes) {
this(iterator, start, end, new HashSet<Attribute>(Arrays
.asList(attributes)));
}
+ /**
+ * Creates an {@code AttributedString} from the given text.
+ *
+ * @param value
+ * the text to take as base for this attributed string.
+ */
public AttributedString(String value) {
if (value == null) {
throw new NullPointerException();
@@ -509,6 +527,20 @@
attributeMap = new HashMap<Attribute, List<Range>>(11);
}
+ /**
+ * Creates an {@code AttributedString} from the given text and the
+ * attributes. The whole text has the given attributes applied.
+ *
+ * @param value
+ * the text to take as base for this attributed string.
+ * @param attributes
+ * the attributes that the text is associated with.
+ * @throws IllegalArgumentException
+ * if the length of {@code value} is 0 but the size of {@code
+ * attributes} is greater than 0.
+ * @throws NullPointerException
+ * if {@code value} is {@code null}.
+ */
public AttributedString(String value,
Map<? extends AttributedCharacterIterator.Attribute, ?> attributes) {
if (value == null) {
@@ -531,6 +563,19 @@
}
}
+ /**
+ * Applies a given attribute to this string.
+ *
+ * @param attribute
+ * the attribute that will be applied to this string.
+ * @param value
+ * the value of the attribute that will be applied to this
+ * string.
+ * @throws IllegalArgumentException
+ * if the length of this attributed string is 0.
+ * @throws NullPointerException
+ * if {@code attribute} is {@code null}.
+ */
public void addAttribute(AttributedCharacterIterator.Attribute attribute,
Object value) {
if (null == attribute) {
@@ -550,6 +595,24 @@
ranges.add(new Range(0, text.length(), value));
}
+ /**
+ * Applies a given attribute to the given range of this string.
+ *
+ * @param attribute
+ * the attribute that will be applied to this string.
+ * @param value
+ * the value of the attribute that will be applied to this
+ * string.
+ * @param start
+ * the start of the range where the attribute will be applied.
+ * @param end
+ * the end of the range where the attribute will be applied.
+ * @throws IllegalArgumentException
+ * if {@code start < 0}, {@code end} is greater than the length
+ * of this string, or if {@code start >= end}.
+ * @throws NullPointerException
+ * if {@code attribute} is {@code null}.
+ */
public void addAttribute(AttributedCharacterIterator.Attribute attribute,
Object value, int start, int end) {
if (null == attribute) {
@@ -631,6 +694,19 @@
it.add(new Range(start, end, value));
}
+ /**
+ * Applies a given set of attributes to the given range of the string.
+ *
+ * @param attributes
+ * the set of attributes that will be applied to this string.
+ * @param start
+ * the start of the range where the attribute will be applied.
+ * @param end
+ * the end of the range where the attribute will be applied.
+ * @throws IllegalArgumentException
+ * if {@code start < 0}, {@code end} is greater than the length
+ * of this string, or if {@code start >= end}.
+ */
public void addAttributes(
Map<? extends AttributedCharacterIterator.Attribute, ?> attributes,
int start, int end) {
@@ -643,15 +719,47 @@
}
}
+ /**
+ * Returns an {@code AttributedCharacterIterator} that gives access to the
+ * complete content of this attributed string.
+ *
+ * @return the newly created {@code AttributedCharacterIterator}.
+ */
public AttributedCharacterIterator getIterator() {
return new AttributedIterator(this);
}
+ /**
+ * Returns an {@code AttributedCharacterIterator} that gives access to the
+ * complete content of this attributed string. Only attributes contained in
+ * {@code attributes} are available from this iterator if they are defined
+ * for this text.
+ *
+ * @param attributes
+ * the array containing attributes that will be in the new
+ * iterator if they are defined for this text.
+ * @return the newly created {@code AttributedCharacterIterator}.
+ */
public AttributedCharacterIterator getIterator(
AttributedCharacterIterator.Attribute[] attributes) {
return new AttributedIterator(this, attributes, 0, text.length());
}
+ /**
+ * Returns an {@code AttributedCharacterIterator} that gives access to the
+ * contents of this attributed string starting at index {@code start} up to
+ * index {@code end}. Only attributes contained in {@code attributes} are
+ * available from this iterator if they are defined for this text.
+ *
+ * @param attributes
+ * the array containing attributes that will be in the new
+ * iterator if they are defined for this text.
+ * @param start
+ * the start index of the iterator on the underlying text.
+ * @param end
+ * the end index of the iterator on the underlying text.
+ * @return the newly created {@code AttributedCharacterIterator}.
+ */
public AttributedCharacterIterator getIterator(
AttributedCharacterIterator.Attribute[] attributes, int start,
int end) {
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Bidi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Bidi.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Bidi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Bidi.java Thu May 7 08:42:00 2009
@@ -20,11 +20,11 @@
import org.apache.harmony.text.internal.nls.Messages;
/**
- * Bidi is the class providing the bidirectional algorithm. The algorithm is
+ * Provides the Unicode Bidirectional Algorithm. The algorithm is
* defined in the Unicode Standard Annex #9, version 13, also described in The
* Unicode Standard, Version 4.0 .
*
- * Use a Bidi object to get the information on the position reordering of a
+ * Use a {@code Bidi} object to get the information on the position reordering of a
* bidirectional text, such as Arabic or Hebrew. The natural display ordering of
* horizontal text in these languages is from right to left, while they order
* numbers from left to right.
@@ -37,25 +37,24 @@
public final class Bidi {
/**
* Constant that indicates the default base level. If there is no strong
- * character, then set the paragraph level to left-to-right.
+ * character, then set the paragraph level to 0 (left-to-right).
*/
public static final int DIRECTION_DEFAULT_LEFT_TO_RIGHT = -2;
/**
* Constant that indicates the default base level. If there is no strong
- * character, then set the paragraph level to right-to-left.
+ * character, then set the paragraph level to 1 (right-to-left).
*/
public static final int DIRECTION_DEFAULT_RIGHT_TO_LEFT = -1;
/**
- * Constant that specifies the default base level as
- * left-to-right.
+ * Constant that specifies the default base level as 0 (left-to-right).
*/
public static final int DIRECTION_LEFT_TO_RIGHT = 0;
/**
- * Constant that specifies the default base level right-to-left.
- */
+ * Constant that specifies the default base level as 1 (right-to-left).
+ */
public static final int DIRECTION_RIGHT_TO_LEFT = 1;
/*
@@ -78,27 +77,26 @@
private com.ibm.icu.text.Bidi icuBidi;
/**
- * Create a Bidi object from the AttributedCharacterIterator of a paragraph
- * text.
- *
- * The RUN_DIRECTION attribute determines the base direction of the
- * bidirectional text. If it's not specified explicitly, the algorithm uses
- * DIRECTION_DEFAULT_LEFT_TO_RIGHT by default.
- *
- * The BIDI_EMBEDDING attribute specifies the level of embedding for each
- * character. Values between -1 and -62 denote overrides at the level's
- * absolute value, values from 1 to 62 indicate embeddings, and the 0 value
- * indicates the level is calculated by the algorithm automatically. For the
- * character with no BIDI_EMBEDDING attribute or with a improper attribute
- * value, such as a null value, the algorithm treats its embedding level as
- * 0.
- *
- * The NUMERIC_SHAPING attribute specifies the instance of NumericShaper
- * used to convert European digits to other decimal digits before performing
- * the bidi algorithm.
- *
+ * Creates a {@code Bidi} object from the {@code
+ * AttributedCharacterIterator} of a paragraph text. The RUN_DIRECTION
+ * attribute determines the base direction of the bidirectional text. If it
+ * is not specified explicitly, the algorithm uses
+ * DIRECTION_DEFAULT_LEFT_TO_RIGHT by default. The BIDI_EMBEDDING attribute
+ * specifies the level of embedding for each character. Values between -1
+ * and -62 denote overrides at the level's absolute value, values from 1 to
+ * 62 indicate embeddings, and the 0 value indicates the level is calculated
+ * by the algorithm automatically. For the character with no BIDI_EMBEDDING
+ * attribute or with a improper attribute value, such as a {@code null}
+ * value, the algorithm treats its embedding level as 0. The NUMERIC_SHAPING
+ * attribute specifies the instance of NumericShaper used to convert
+ * European digits to other decimal digits before performing the bidi
+ * algorithm.
+ *
* @param paragraph
- *
+ * the String containing the paragraph text to perform the
+ * algorithm.
+ * @throws IllegalArgumentException
+ * if {@code paragraph} is {@code null}.
* @see java.awt.font.TextAttribute#BIDI_EMBEDDING
* @see java.awt.font.TextAttribute#NUMERIC_SHAPING
* @see java.awt.font.TextAttribute#RUN_DIRECTION
@@ -113,32 +111,33 @@
}
/**
- * Create a Bidi object.
+ * Creates a {@code Bidi} object.
*
* @param text
- * the char array of the paragraph text.
+ * the char array of the paragraph text that is processed.
* @param textStart
- * the start offset of the text array to perform the algorithm.
+ * the index in {@code text} of the start of the paragraph.
* @param embeddings
* the embedding level array of the paragraph text, specifying
* the embedding level information for each character. Values
- * between -1 and -62 denote overrides at the level's absolute
- * value, values from 1 to 62 indicate embeddings, and the 0
+ * between -1 and -61 denote overrides at the level's absolute
+ * value, values from 1 to 61 indicate embeddings, and the 0
* value indicates the level is calculated by the algorithm
* automatically.
* @param embStart
- * the start offset of the embeddings array to perform the
- * algorithm.
+ * the index in {@code embeddings} of the start of the paragraph.
* @param paragraphLength
- * the length of the text to perform the algorithm. It must be
- * text.length >= textStart + paragraphLength, and
- * embeddings.length >= embStart + paragraphLength.
+ * the length of the text to perform the algorithm.
* @param flags
* indicates the base direction of the bidirectional text. It is
* expected that this will be one of the direction constant
* values defined in this class. An unknown value is treated as
* DIRECTION_DEFAULT_LEFT_TO_RIGHT.
- *
+ * @throws IllegalArgumentException
+ * if {@code textStart}, {@code embStart}, or {@code
+ * paragraphLength} is negative; if
+ * {@code text.length < textStart + paragraphLength} or
+ * {@code embeddings.length < embStart + paragraphLength}.
* @see #DIRECTION_LEFT_TO_RIGHT
* @see #DIRECTION_RIGHT_TO_LEFT
* @see #DIRECTION_DEFAULT_RIGHT_TO_LEFT
@@ -178,17 +177,16 @@
}
/**
- * Create a Bidi object.
+ * Creates a {@code Bidi} object.
*
* @param paragraph
- * the String containing the paragraph text to perform the
- * algorithm.
+ * the string containing the paragraph text to perform the
+ * algorithm on.
* @param flags
* indicates the base direction of the bidirectional text. It is
* expected that this will be one of the direction constant
* values defined in this class. An unknown value is treated as
* DIRECTION_DEFAULT_LEFT_TO_RIGHT.
- *
* @see #DIRECTION_LEFT_TO_RIGHT
* @see #DIRECTION_RIGHT_TO_LEFT
* @see #DIRECTION_DEFAULT_RIGHT_TO_LEFT
@@ -205,7 +203,7 @@
}
/**
- * Return whether the base level is from left to right.
+ * Returns whether the base level is from left to right.
*
* @return true if the base level is from left to right.
*/
@@ -214,8 +212,8 @@
}
/**
- * Create a new Bidi object containing the information of one line from this
- * object.
+ * Creates a new {@code Bidi} object containing the information of one line
+ * from this object.
*
* @param lineStart
* the start offset of the line.
@@ -223,6 +221,10 @@
* the limit of the line.
* @return the new line Bidi object. In this new object, the indices will
* range from 0 to (limit - start - 1).
+ * @throws IllegalArgumentException
+ * if {@code lineStart < 0}, {@code lineLimit < 0}, {@code
+ * lineStart > lineLimit} or if {@code lineStart} is greater
+ * than the length of this object's paragraph text.
*/
public Bidi createLineBidi(int lineStart, int lineLimit) {
int length = icuBidi.getLength();
@@ -239,29 +241,29 @@
}
/**
- * Return the base level.
+ * Returns the base level.
*
- * @return the int value of the base level.
+ * @return the base level.
*/
public int getBaseLevel() {
return icuBidi.getBaseLevel();
}
/**
- * Return the length of the text in the Bidi object.
+ * Returns the length of the text in the {@code Bidi} object.
*
- * @return the int value of the length.
+ * @return the length.
*/
public int getLength() {
return icuBidi.getLength();
}
/**
- * Return the level of a specified character.
+ * Returns the level of a specified character.
*
* @param offset
* the offset of the character.
- * @return the int value of the level.
+ * @return the level.
*/
public int getLevelAt(int offset) {
try {
@@ -272,9 +274,9 @@
}
/**
- * Return the number of runs in the bidirectional text.
+ * Returns the number of runs in the bidirectional text.
*
- * @return the int value of runs, at least 1.
+ * @return the number of runs, at least 1.
*/
public int getRunCount() {
int runCount = icuBidi.getRunCount();
@@ -282,7 +284,7 @@
}
/**
- * Return the level of a specified run.
+ * Returns the level of the specified run.
*
* @param run
* the index of the run.
@@ -297,7 +299,7 @@
}
/**
- * Return the limit offset of a specified run.
+ * Returns the limit offset of the specified run.
*
* @param run
* the index of the run.
@@ -312,7 +314,7 @@
}
/**
- * Return the start offset of a specified run.
+ * Returns the start offset of the specified run.
*
* @param run
* the index of the run.
@@ -327,40 +329,43 @@
}
/**
- * Return whether the text is from left to right, that is, both the base
+ * Indicates whether the text is from left to right, that is, both the base
* direction and the text direction is from left to right.
*
- * @return true if the text is from left to right.
+ * @return {@code true} if the text is from left to right; {@code false}
+ * otherwise.
*/
public boolean isLeftToRight() {
return icuBidi.isLeftToRight();
}
/**
- * Return whether the text direction is mixed.
+ * Indicates whether the text direction is mixed.
*
- * @return true if the text direction is mixed.
+ * @return {@code true} if the text direction is mixed; {@code false}
+ * otherwise.
*/
public boolean isMixed() {
return icuBidi.isMixed();
}
/**
- * Return whether the text is from right to left, that is, both the base
+ * Indicates whether the text is from right to left, that is, both the base
* direction and the text direction is from right to left.
*
- * @return true if the text is from right to left.
+ * @return {@code true} if the text is from right to left; {@code false}
+ * otherwise.
*/
public boolean isRightToLeft() {
return icuBidi.isRightToLeft();
}
/**
- * Reorder a range of objects according to their specified levels. This is a
- * convenience function that does not use a Bidi object. The range of
- * objects at index from objectStart to objectStart + count will be
- * reordered according to the range of levels at index from levelStart to
- * levelStart + count.
+ * Reorders a range of objects according to their specified levels. This is
+ * a convenience function that does not use a {@code Bidi} object. The range
+ * of objects at {@code index} from {@code objectStart} to {@code
+ * objectStart + count} will be reordered according to the range of levels
+ * at {@code index} from {@code levelStart} to {@code levelStart + count}.
*
* @param levels
* the level array, which is already determined.
@@ -372,6 +377,10 @@
* the start offset of the range of objects.
* @param count
* the count of the range of objects to reorder.
+ * @throws IllegalArgumentException
+ * if {@code count}, {@code levelStart} or {@code objectStart}
+ * is negative; if {@code count > levels.length - levelStart} or
+ * if {@code count > objects.length - objectStart}.
*/
public static void reorderVisually(byte[] levels, int levelStart,
Object[] objects, int objectStart, int count) {
@@ -389,8 +398,8 @@
}
/**
- * Return whether a range of characters of a text requires a Bidi object to
- * display properly.
+ * Indicates whether a range of characters of a text requires a {@code Bidi}
+ * object to display properly.
*
* @param text
* the char array of the text.
@@ -398,7 +407,12 @@
* the start offset of the range of characters.
* @param limit
* the limit offset of the range of characters.
- * @return true if the range of characters requires a Bidi object.
+ * @return {@code true} if the range of characters requires a {@code Bidi}
+ * object; {@code false} otherwise.
+ * @throws IllegalArgumentException
+ * if {@code start} or {@code limit} is negative; {@code start >
+ * limit} or {@code limit} is greater than the length of this
+ * object's paragraph text.
*/
public static boolean requiresBidi(char[] text, int start, int limit) {
//int length = text.length;
@@ -410,7 +424,8 @@
}
/**
- * Return the internal message of the Bidi object, used in debugging.
+ * Returns the internal message of the {@code Bidi} object, used in
+ * debugging.
*
* @return a string containing the internal message.
*/
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/BreakIterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/BreakIterator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/BreakIterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/BreakIterator.java Thu May 7 08:42:00 2009
@@ -20,32 +20,204 @@
import java.util.Locale;
/**
- * This class is used to locate the boundaries of text. Instance of this class
- * can be got by some factory methods:
+ * Locates boundaries in text. This class defines a protocol for objects that
+ * break up a piece of natural-language text according to a set of criteria.
+ * Instances or subclasses of {@code BreakIterator} can be provided, for
+ * example, to break a piece of text into words, sentences, or logical
+ * characters according to the conventions of some language or group of
+ * languages. We provide four built-in types of {@code BreakIterator}:
* <ul>
- * <li>
- * <code>getCharacterInstance()<code> returns a BreakIterator that iterate the
- * logical characters without worrying about how the character is stored. For
- * example, some character may be stored in more than one Unicode code point
- * according to Unicode specification, this character can handle the logical
- * characters with multi code points.</li>
- * <li>
- * <code>getWordInstance()<code> returns a <code>BreakIterator</code> that
- * iterate the word-breaks. The beginning and end of each word(including numbers)
- * is treated as boundary position. Whitespace and punctuation are kept separate
- * from real words.</li>
- * <li>
- * <code>getSentenceInstance()</code> returns a BreakIterator that iterate the
- * sentence-breaks.</li>
- * <li><code>getLineInstance()</code> returns a BreakIterator that iterate the
- * line-breaks which can be used to wrap lines. This iterator can handle whitespaces,
- * hyphens and punctuations.
+ * <li>{@link #getSentenceInstance()} returns a {@code BreakIterator} that
+ * locates boundaries between sentences. This is useful for triple-click
+ * selection, for example.</li>
+ * <li>{@link #getWordInstance()} returns a {@code BreakIterator} that locates
+ * boundaries between words. This is useful for double-click selection or "find
+ * whole words" searches. This type of {@code BreakIterator} makes sure there is
+ * a boundary position at the beginning and end of each legal word (numbers
+ * count as words, too). Whitespace and punctuation are kept separate from real
+ * words.</li>
+ * <li>{@code getLineInstance()} returns a {@code BreakIterator} that locates
+ * positions where it is legal for a text editor to wrap lines. This is similar
+ * to word breaking, but not the same: punctuation and whitespace are generally
+ * kept with words (you don't want a line to start with whitespace, for
+ * example), and some special characters can force a position to be considered a
+ * line break position or prevent a position from being a line break position.</li>
+ * <li>{@code getCharacterInstance()} returns a {@code BreakIterator} that
+ * locates boundaries between logical characters. Because of the structure of
+ * the Unicode encoding, a logical character may be stored internally as more
+ * than one Unicode code point. (A with an umlaut may be stored as an a followed
+ * by a separate combining umlaut character, for example, but the user still
+ * thinks of it as one character.) This iterator allows various processes
+ * (especially text editors) to treat as characters the units of text that a
+ * user would think of as characters, rather than the units of text that the
+ * computer sees as "characters".</li>
+ * </ul> {@code BreakIterator}'s interface follows an "iterator" model (hence
+ * the name), meaning it has a concept of a "current position" and methods like
+ * {@code first()}, {@code last()}, {@code next()}, and {@code previous()} that
+ * update the current position. All {@code BreakIterator}s uphold the following
+ * invariants:
+ * <ul>
+ * <li>The beginning and end of the text are always treated as boundary
+ * positions.</li>
+ * <li>The current position of the iterator is always a boundary position
+ * (random- access methods move the iterator to the nearest boundary position
+ * before or after the specified position, not <i>to</i> the specified
+ * position).</li>
+ * <li>{@code DONE} is used as a flag to indicate when iteration has stopped.
+ * {@code DONE} is only returned when the current position is the end of the
+ * text and the user calls {@code next()}, or when the current position is the
+ * beginning of the text and the user calls {@code previous()}.</li>
+ * <li>Break positions are numbered by the positions of the characters that
+ * follow them. Thus, under normal circumstances, the position before the first
+ * character is 0, the position after the first character is 1, and the position
+ * after the last character is 1 plus the length of the string.</li>
+ * <li>The client can change the position of an iterator, or the text it
+ * analyzes, at will, but cannot change the behavior. If the user wants
+ * different behavior, he must instantiate a new iterator.</li>
* </ul>
- *
- * <code>BreakIterator</code> uses <code>CharacterIterator</code> to perform the
- * analysis, so that any storage which provides <code>CharacterIterator</code>
- * interface.
- *
+ * <p>
+ * {@code BreakIterator} accesses the text it analyzes through a
+ * {@link CharacterIterator}, which makes it possible to use {@code
+ * BreakIterator} to analyze text in any text-storage vehicle that provides a
+ * {@code CharacterIterator} interface.
+ * <p>
+ * <em>Note:</em> Some types of {@code BreakIterator} can take a long time to
+ * create, and instances of {@code BreakIterator} are not currently cached by
+ * the system. For optimal performance, keep instances of {@code BreakIterator}
+ * around as long as it makes sense. For example, when word-wrapping a document,
+ * don't create and destroy a new {@code BreakIterator} for each line. Create
+ * one break iterator for the whole document (or whatever stretch of text you're
+ * wrapping) and use it to do the whole job of wrapping the text.
+ * <p>
+ * <em>Examples</em>:
+ * <p>
+ * Creating and using text boundaries:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void main(String args[]) {
+ * if (args.length == 1) {
+ * String stringToExamine = args[0];
+ * //print each word in order
+ * BreakIterator boundary = BreakIterator.getWordInstance();
+ * boundary.setText(stringToExamine);
+ * printEachForward(boundary, stringToExamine);
+ * //print each sentence in reverse order
+ * boundary = BreakIterator.getSentenceInstance(Locale.US);
+ * boundary.setText(stringToExamine);
+ * printEachBackward(boundary, stringToExamine);
+ * printFirst(boundary, stringToExamine);
+ * printLast(boundary, stringToExamine);
+ * }
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Print each element in order:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void printEachForward(BreakIterator boundary, String source) {
+ * int start = boundary.first();
+ * for (int end = boundary.next(); end != BreakIterator.DONE; start = end, end = boundary.next()) {
+ * System.out.println(source.substring(start, end));
+ * }
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Print each element in reverse order:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void printEachBackward(BreakIterator boundary, String source) {
+ * int end = boundary.last();
+ * for (int start = boundary.previous(); start != BreakIterator.DONE; end = start, start = boundary
+ * .previous()) {
+ * System.out.println(source.substring(start, end));
+ * }
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Print the first element:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void printFirst(BreakIterator boundary, String source) {
+ * int start = boundary.first();
+ * int end = boundary.next();
+ * System.out.println(source.substring(start, end));
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Print the last element:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void printLast(BreakIterator boundary, String source) {
+ * int end = boundary.last();
+ * int start = boundary.previous();
+ * System.out.println(source.substring(start, end));
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Print the element at a specified position:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void printAt(BreakIterator boundary, int pos, String source) {
+ * int end = boundary.following(pos);
+ * int start = boundary.previous();
+ * System.out.println(source.substring(start, end));
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Find the next word:
+ * <blockquote>
+ *
+ * <pre>
+ * public static int nextWordStartAfter(int pos, String text) {
+ * BreakIterator wb = BreakIterator.getWordInstance();
+ * wb.setText(text);
+ * int last = wb.following(pos);
+ * int current = wb.next();
+ * while (current != BreakIterator.DONE) {
+ * for (int p = last; p < current; p++) {
+ * if (Character.isLetter(text.charAt(p)))
+ * return last;
+ * }
+ * last = current;
+ * current = wb.next();
+ * }
+ * return BreakIterator.DONE;
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * The iterator returned by {@code BreakIterator.getWordInstance()} is unique in
+ * that the break positions it returns don't represent both the start and end of
+ * the thing being iterated over. That is, a sentence-break iterator returns
+ * breaks that each represent the end of one sentence and the beginning of the
+ * next. With the word-break iterator, the characters between two boundaries
+ * might be a word, or they might be the punctuation or whitespace between two
+ * words. The above code uses a simple heuristic to determine which boundary is
+ * the beginning of a word: If the characters between this boundary and the next
+ * boundary include at least one letter (this can be an alphabetical letter, a
+ * CJK ideograph, a Hangul syllable, a Kana character, etc.), then the text
+ * between this boundary and the next is a word; otherwise, it's the material
+ * between words.)
+ *
* @see CharacterIterator
*/
public abstract class BreakIterator implements Cloneable {
@@ -56,8 +228,8 @@
* -----------------------------------------------------------------------
*/
/**
- * This constant is returned by iterate methods like previous() or next() if
- * they have returned all valid boundaries.
+ * This constant is returned by iterate methods like {@code previous()} or
+ * {@code next()} if they have returned all valid boundaries.
*/
public static final int DONE = -1;
@@ -100,20 +272,19 @@
* -----------------------------------------------------------------------
*/
/**
- * Return all supported locales.
+ * Returns all supported locales in an array.
*
- * @return all supported locales
+ * @return all supported locales.
*/
public static Locale[] getAvailableLocales() {
return com.ibm.icu.text.BreakIterator.getAvailableLocales();
}
/**
- * Return a new instance of BreakIterator used to iterate characters using
- * default locale.
+ * Returns a new instance of {@code BreakIterator} to iterate over
+ * characters using the default locale.
*
- * @return a new instance of BreakIterator used to iterate characters using
- * default locale.
+ * @return a new instance of {@code BreakIterator} using the default locale.
*/
public static BreakIterator getCharacterInstance() {
return new RuleBasedBreakIterator(com.ibm.icu.text.BreakIterator
@@ -121,13 +292,12 @@
}
/**
- * Return a new instance of BreakIterator used to iterate characters using
- * given locale.
+ * Returns a new instance of {@code BreakIterator} to iterate over
+ * characters using the given locale.
*
* @param where
- * the given locale
- * @return a new instance of BreakIterator used to iterate characters using
- * given locale.
+ * the given locale.
+ * @return a new instance of {@code BreakIterator} using the given locale.
*/
public static BreakIterator getCharacterInstance(Locale where) {
if (where == null) {
@@ -139,11 +309,10 @@
}
/**
- * Return a new instance of BreakIterator used to iterate line-breaks using
- * default locale.
+ * Returns a new instance of {{@code BreakIterator} to iterate over
+ * line breaks using the default locale.
*
- * @return a new instance of BreakIterator used to iterate line-breaks using
- * default locale.
+ * @return a new instance of {@code BreakIterator} using the default locale.
*/
public static BreakIterator getLineInstance() {
return new RuleBasedBreakIterator(com.ibm.icu.text.BreakIterator
@@ -151,13 +320,13 @@
}
/**
- * Return a new instance of BreakIterator used to iterate line-breaks using
- * given locale.
+ * Returns a new instance of {@code BreakIterator} to iterate over
+ * line breaks using the given locale.
*
* @param where
- * the given locale
- * @return a new instance of BreakIterator used to iterate line-breaks using
- * given locale.
+ * the given locale.
+ * @return a new instance of {@code BreakIterator} using the given locale.
+ * @throws NullPointerException if {@code where} is {@code null}.
*/
public static BreakIterator getLineInstance(Locale where) {
if (where == null) {
@@ -169,11 +338,10 @@
}
/**
- * Return a new instance of BreakIterator used to iterate sentence-breaks
- * using default locale.
+ * Returns a new instance of {@code BreakIterator} to iterate over
+ * sentence-breaks using the default locale.
*
- * @return a new instance of BreakIterator used to iterate sentence-breaks
- * using default locale.
+ * @return a new instance of {@code BreakIterator} using the default locale.
*/
public static BreakIterator getSentenceInstance() {
return new RuleBasedBreakIterator(com.ibm.icu.text.BreakIterator
@@ -181,13 +349,13 @@
}
/**
- * Return a new instance of BreakIterator used to iterate sentence-breaks
- * using given locale.
+ * Returns a new instance of {@code BreakIterator} to iterate over
+ * sentence-breaks using the given locale.
*
* @param where
- * the given locale
- * @return a new instance of BreakIterator used to iterate sentence-breaks
- * using given locale.
+ * the given locale.
+ * @return a new instance of {@code BreakIterator} using the given locale.
+ * @throws NullPointerException if {@code where} is {@code null}.
*/
public static BreakIterator getSentenceInstance(Locale where) {
if (where == null) {
@@ -199,11 +367,10 @@
}
/**
- * Return a new instance of BreakIterator used to iterate word-breaks using
- * default locale.
+ * Returns a new instance of {@code BreakIterator} to iterate over
+ * word-breaks using the default locale.
*
- * @return a new instance of BreakIterator used to iterate word-breaks using
- * default locale.
+ * @return a new instance of {@code BreakIterator} using the default locale.
*/
public static BreakIterator getWordInstance() {
return new RuleBasedBreakIterator(com.ibm.icu.text.BreakIterator
@@ -211,13 +378,13 @@
}
/**
- * Return a new instance of BreakIterator used to iterate word-breaks using
- * given locale.
+ * Returns a new instance of {@code BreakIterator} to iterate over
+ * word-breaks using the given locale.
*
* @param where
- * the given locale
- * @return a new instance of BreakIterator used to iterate word-breaks using
- * given locale.
+ * the given locale.
+ * @return a new instance of {@code BreakIterator} using the given locale.
+ * @throws NullPointerException if {@code where} is {@code null}.
*/
public static BreakIterator getWordInstance(Locale where) {
if (where == null) {
@@ -229,42 +396,42 @@
}
/**
- * Return true if the given offset is a boundary position. If this method
+ * Indicates whether the given offset is a boundary position. If this method
* returns true, the current iteration position is set to the given
* position; if the function returns false, the current iteration position
- * is set as though following() had been called.
+ * is set as though {@link #following(int)} had been called.
*
* @param offset
- * the given offset to check
- * @return true if the given offset is a boundary position
+ * the given offset to check.
+ * @return {@code true} if the given offset is a boundary position; {@code
+ * false} otherwise.
*/
public boolean isBoundary(int offset) {
return wrapped.isBoundary(offset);
}
/**
- * Return the position of last boundary precede the given offset, and set
- * current position to returned value, or <code>DONE</code> if the given
- * offset specifies the starting position.
- * <p>
- * <code>IllegalArgumentException</code> will be thrown if given offset is
- * invalid.
- * </p>
- *
+ * Returns the position of last boundary preceding the given offset, and
+ * sets the current position to the returned value, or {@code DONE} if the
+ * given offset specifies the starting position.
+ *
* @param offset
- * the given start position to be searched for
- * @return the position of last boundary precede the given offset
+ * the given start position to be searched for.
+ * @return the position of the last boundary preceding the given offset.
+ * @throws IllegalArgumentException
+ * if the offset is invalid.
*/
public int preceding(int offset) {
return wrapped.preceding(offset);
}
/**
- * Set the new text string to be analyzed, the current position will be
- * reset to beginning of this new string, and the old string will lost.
+ * Sets the new text string to be analyzed, the current position will be
+ * reset to the beginning of this new string, and the old string will be
+ * lost.
*
* @param newText
- * the new text string to be analyzed
+ * the new text string to be analyzed.
*/
public void setText(String newText) {
wrapped.setText(newText);
@@ -276,92 +443,90 @@
* -----------------------------------------------------------------------
*/
/**
- * Return this iterator's current position.
+ * Returns this iterator's current position.
*
- * @return this iterator's current position
+ * @return this iterator's current position.
*/
public abstract int current();
/**
- * Set this iterator's current position to the first boundary, and return
- * this position.
+ * Sets this iterator's current position to the first boundary and returns
+ * that position.
*
- * @return the position of first boundary
+ * @return the position of the first boundary.
*/
public abstract int first();
/**
- * Set the position of the first boundary following the given offset, and
- * return this position. If there is no boundary after the given offset,
- * return DONE.
- * <p>
- * <code>IllegalArgumentException</code> will be thrown if given offset is
- * invalid.
- * </p>
- *
+ * Sets the position of the first boundary to the one following the given
+ * offset and returns this position. Returns {@code DONE} if there is no
+ * boundary after the given offset.
+ *
* @param offset
- * the given position to be searched for
- * @return the position of the first boundary following the given offset
+ * the given position to be searched for.
+ * @return the position of the first boundary following the given offset.
+ * @throws IllegalArgumentException
+ * if the offset is invalid.
*/
public abstract int following(int offset);
/**
- * Return a <code>CharacterIterator</code> which represents the text being
+ * Returns a {@code CharacterIterator} which represents the text being
* analyzed. Please note that the returned value is probably the internal
- * iterator used by this object, so that if the invoker want to modify the
- * status of the returned iterator, a clone operation at first is
- * recommended.
+ * iterator used by this object. If the invoker wants to modify the status
+ * of the returned iterator, it is recommended to first create a clone of
+ * the iterator returned.
*
- * @return a <code>CharacterIterator</code> which represents the text
- * being analyzed.
+ * @return a {@code CharacterIterator} which represents the text being
+ * analyzed.
*/
public abstract CharacterIterator getText();
/**
- * Set this iterator's current position to the last boundary, and return
- * this position.
+ * Sets this iterator's current position to the last boundary and returns
+ * that position.
*
- * @return the position of last boundary
+ * @return the position of last boundary.
*/
public abstract int last();
/**
- * Set this iterator's current position to the next boundary after current
- * position, and return this position. Return <code>DONE</code> if no
- * boundary found after current position.
+ * Sets this iterator's current position to the next boundary after the
+ * current position, and returns this position. Returns {@code DONE} if no
+ * boundary was found after the current position.
*
- * @return the position of last boundary
+ * @return the position of last boundary.
*/
public abstract int next();
/**
- * Set this iterator's current position to the next boundary after the given
- * position, and return this position. Return <code>DONE</code> if no
- * boundary found after the given position.
+ * Sets this iterator's current position to the next boundary after the
+ * given position, and returns that position. Returns {@code DONE} if no
+ * boundary was found after the given position.
*
* @param n
* the given position.
- * @return the position of last boundary
+ * @return the position of last boundary.
*/
public abstract int next(int n);
/**
- * Set this iterator's current position to the previous boundary before
- * current position, and return this position. Return <code>DONE</code> if
- * no boundary found before current position.
+ * Sets this iterator's current position to the previous boundary before the
+ * current position and returns that position. Returns {@code DONE} if
+ * no boundary was found before the current position.
*
- * @return the position of last boundary
+ * @return the position of last boundary.
*/
public abstract int previous();
/**
- * Set new text to be analyzed by given <code>CharacterIterator</code>.
+ * Sets the new text to be analyzed by the given {@code CharacterIterator}.
* The position will be reset to the beginning of the new text, and other
- * status of this iterator will be kept.
+ * status information of this iterator will be kept.
*
* @param newText
- * the given <code>CharacterIterator</code> refer to the text
- * to be analyzed
+ * the {@code CharacterIterator} referring to the text to be
+ * analyzed.
*/
public abstract void setText(CharacterIterator newText);
@@ -371,10 +536,10 @@
* -----------------------------------------------------------------------
*/
/**
- * Create copy of this iterator, all status including current position is
- * kept.
+ * Creates a copy of this iterator, all status information including the
+ * current position are kept the same.
*
- * @return copy of this iterator
+ * @return a copy of this iterator.
*/
@Override
public Object clone() {
@@ -388,13 +553,19 @@
}
/**
- * Get a long value from the given byte array, start from given offset.
+ * Gets a long value from the given byte array, starting from the given
+ * offset.
*
* @param buf
- * the bytes to be converted
+ * the bytes to be converted.
* @param offset
- * the start position of conversion
- * @return the converted long value
+ * the start position of the conversion.
+ * @return the converted long value.
+ * @throws NullPointerException
+ * if {@code buf} is {@code null}.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code offset < 0} or {@code offset + LONG_LENGTH} is
+ * greater than the length of {@code buf}.
*/
protected static long getLong(byte[] buf, int offset) {
if (null == buf) {
@@ -411,13 +582,19 @@
}
/**
- * Get an int value from the given byte array, start from given offset.
+ * Gets an int value from the given byte array, starting from the given
+ * offset.
*
* @param buf
- * the bytes to be converted
+ * the bytes to be converted.
* @param offset
- * the start position of conversion
- * @return the converted int value
+ * the start position of the conversion.
+ * @return the converted int value.
+ * @throws NullPointerException
+ * if {@code buf} is {@code null}.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code offset < 0} or {@code offset + INT_LENGTH} is
+ * greater than the length of {@code buf}.
*/
protected static int getInt(byte[] buf, int offset) {
if (null == buf) {
@@ -434,13 +611,19 @@
}
/**
- * Get a short value from the given byte array, start from given offset.
+ * Gets a short value from the given byte array, starting from the given
+ * offset.
*
* @param buf
- * the bytes to be converted
+ * the bytes to be converted.
* @param offset
- * the start position of conversion
- * @return the converted short value
+ * the start position of the conversion.
+ * @return the converted short value.
+ * @throws NullPointerException
+ * if {@code buf} is {@code null}.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code offset < 0} or {@code offset + SHORT_LENGTH} is
+ * greater than the length of {@code buf}.
*/
protected static short getShort(byte[] buf, int offset) {
if (null == buf) {
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CharacterIterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CharacterIterator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CharacterIterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CharacterIterator.java Thu May 7 08:42:00 2009
@@ -18,96 +18,99 @@
package java.text;
/**
- * CharacterIterator is used to sequence over a group of characters. The
- * iteration starts at the begin index in the group of character and continues
+ * An interface for the bidirectional iteration over a group of characters. The
+ * iteration starts at the begin index in the group of characters and continues
* to one index before the end index.
*/
public interface CharacterIterator extends Cloneable {
/**
- * A constant which indicates there is no character.
+ * A constant which indicates that there is no character at the current
+ * index.
*/
public static final char DONE = '\uffff';
/**
- * Answers a new CharacterIterator with the same properties.
+ * Returns a new {@code CharacterIterator} with the same properties.
*
- * @return a shallow copy of this CharacterIterator
+ * @return a shallow copy of this character iterator.
*
* @see java.lang.Cloneable
*/
public Object clone();
/**
- * Answers the character at the current index.
+ * Returns the character at the current index.
*
- * @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 beginning or end of the sequence.
*/
public char current();
/**
- * 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.
*
- * @return the character at the begin index
+ * @return the character at the begin index.
*/
public char first();
/**
- * Answers the begin index.
+ * Returns the begin index.
*
- * @return the index of the first character to iterate
+ * @return the index of the first character of the iteration.
*/
public int getBeginIndex();
/**
- * Answers the end index.
+ * Returns the end index.
*
- * @return the index one past the last character to iterate
+ * @return the index one past the last character of the iteration.
*/
public int getEndIndex();
/**
- * Answers the current index.
+ * Returns the current index.
*
- * @return the current index
+ * @return the current index.
*/
public int getIndex();
/**
- * 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.
*/
public char last();
/**
* 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();
/**
* 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();
/**
- * Sets the current index.
+ * Sets the current index to a new position and returns the character at the
+ * new index.
*
- * @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 new index that this character iterator is set to.
+ * @return the character at the new index, or {@code DONE} if the index is
+ * past the end.
+ * @throws IllegalArgumentException
+ * if {@code location} is less than the begin index or greater than
+ * the end index.
*/
public char setIndex(int location);
}