From: Andy Heninger Date: Thu, 13 Sep 2018 19:46:17 +0000 (-0700) Subject: ICU-13801 Clarify Javadoc for BreakIterator.setText() (#69) X-Git-Tag: release-63-rc~72 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=b54702b7de9fb40622a815cc4a531bb2e2c4e965;p=icu ICU-13801 Clarify Javadoc for BreakIterator.setText() (#69) --- diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/BreakIterator.java b/icu4j/main/classes/core/src/com/ibm/icu/text/BreakIterator.java index a8a953ba901..77cdc37bb44 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/text/BreakIterator.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/text/BreakIterator.java @@ -488,12 +488,19 @@ public abstract class BreakIterator implements Cloneable /** * Returns a CharacterIterator over the text being analyzed. - * For at least some subclasses of BreakIterator, this is a reference - * to the actual iterator being used by the BreakIterator, - * and therefore, this function's return value should be treated as - * const. No guarantees are made about the current position - * of this iterator when it is returned. If you need to move that + *

+ * Caution:The state of the returned CharacterIterator + * must not be modified in any way while the BreakIterator is still in use. + * Doing so will lead to undefined behavior of the BreakIterator. + * Clone the returned CharacterIterator first and work with that. + *

+ * The returned CharacterIterator is a reference + * to the actual iterator being used by the BreakIterator. + * No guarantees are made about the current position + * of this iterator when it is returned; it may differ from the + * BreakIterators current position. If you need to move that * position to examine the text, clone this function's return value first. + * * @return A CharacterIterator over the text being analyzed. * @stable ICU 2.0 */ @@ -518,6 +525,10 @@ public abstract class BreakIterator implements Cloneable * piece of text is passed in as a CharSequence, and the current * iteration position is reset to the beginning of the text. * (The old text is dropped.) + *

+ * The text underlying the CharSequence must not be be modified while + * the BreakIterator holds a references to it. (As could possibly occur + * with a StringBuilder, for example). * @param newText A CharSequence containing the text to analyze with * this BreakIterator. * @draft ICU 60 @@ -527,11 +538,15 @@ public abstract class BreakIterator implements Cloneable } /** - * Sets the iterator to analyze a new piece of text. The - * BreakIterator is passed a CharacterIterator through which - * it will access the text itself. The current iteration - * position is reset to the CharacterIterator's start index. + * Sets the iterator to analyze a new piece of text. This function resets + * the current iteration position to the beginning of the text. * (The old iterator is dropped.) + *

+ * Caution: The supplied CharacterIterator is used + * directly by the BreakIterator, and must not be altered in any + * way by code outside of the BreakIterator. + * Doing so will lead to undefined behavior of the BreakIterator. + * * @param newText A CharacterIterator referring to the text * to analyze with this BreakIterator (the iterator's current * position is ignored, but its other state is significant). diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/RuleBasedBreakIterator.java b/icu4j/main/classes/core/src/com/ibm/icu/text/RuleBasedBreakIterator.java index a0529a83d25..b9680f33c05 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/text/RuleBasedBreakIterator.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/text/RuleBasedBreakIterator.java @@ -48,7 +48,7 @@ public class RuleBasedBreakIterator extends BreakIterator { private RuleBasedBreakIterator() { fDictionaryCharCount = 0; synchronized(gAllBreakEngines) { - fBreakEngines = new ArrayList(gAllBreakEngines); + fBreakEngines = new ArrayList<>(gAllBreakEngines); } } @@ -136,7 +136,7 @@ public class RuleBasedBreakIterator extends BreakIterator { result.fText = (CharacterIterator)(fText.clone()); } synchronized (gAllBreakEngines) { - result.fBreakEngines = new ArrayList(gAllBreakEngines); + result.fBreakEngines = new ArrayList<>(gAllBreakEngines); } result.fLookAheadMatches = new LookAheadResults(); result.fBreakCache = result.new BreakCache(fBreakCache); @@ -300,7 +300,7 @@ public class RuleBasedBreakIterator extends BreakIterator { static { gUnhandledBreakEngine = new UnhandledBreakEngine(); - gAllBreakEngines = new ArrayList(); + gAllBreakEngines = new ArrayList<>(); gAllBreakEngines.add(gUnhandledBreakEngine); } @@ -617,10 +617,19 @@ public class RuleBasedBreakIterator extends BreakIterator { } /** - * Return a CharacterIterator over the text being analyzed. This version - * of this method returns the actual CharacterIterator we're using internally. - * Changing the state of this iterator can have undefined consequences. If - * you need to change it, clone it first. + * Returns a CharacterIterator over the text being analyzed. + *

+ * Caution:The state of the returned CharacterIterator + * must not be modified in any way while the BreakIterator is still in use. + * Doing so will lead to undefined behavior of the BreakIterator. + * Clone the returned CharacterIterator first and work with that. + *

+ * The returned CharacterIterator is a reference + * to the actual iterator being used by the BreakIterator. + * No guarantees are made about the current position + * of this iterator when it is returned; it may differ from the + * BreakIterators current position. If you need to move that + * position to examine the text, clone this function's return value first. * @return An iterator over the text being analyzed. * @stable ICU 2.0 */ @@ -632,6 +641,13 @@ public class RuleBasedBreakIterator extends BreakIterator { /** * Set the iterator to analyze a new piece of text. This function resets * the current iteration position to the beginning of the text. + * (The old iterator is dropped.) + *

+ * Caution: The supplied CharacterIterator is used + * directly by the BreakIterator, and must not be altered in any + * way by code outside of the BreakIterator. + * Doing so will lead to undefined behavior of the BreakIterator. + * * @param newText An iterator over the text to analyze. * @stable ICU 2.0 */