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 a8a953ba901fe460941a5108f51f5a6688981849..77cdc37bb44414298f18a3db41b86159ed04c995 100644 (file)
--- 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 <b>actual iterator being used</b> by the BreakIterator,
-     * and therefore, this function's return value should be treated as
-     * <tt>const</tt>.  No guarantees are made about the current position
-     * of this iterator when it is returned.  If you need to move that
+     * <p>
+     * <b><i>Caution:</i></b>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.
+     * <p>
+     * The returned CharacterIterator is a reference
+     * to the <b>actual iterator being used</b> 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.)
+     * <p>
+     * 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.)
+     * <p>
+     * <b><i>Caution:</i></b> 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 a0529a83d25e1d04082f28e76fc0cc1c4d23f914..b9680f33c05d4ff595d03f32659de2e09fbf672f 100644 (file)
--- 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<LanguageBreakEngine>(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<LanguageBreakEngine>(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<LanguageBreakEngine>();
+        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.
+     * <p>
+     * <b><i>Caution:</i></b>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.
+     * <p>
+     * The returned CharacterIterator is a reference
+     * to the <b>actual iterator being used</b> 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.)
+     * <p>
+     * <b><i>Caution:</i></b> 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
      */