ICU-511.25.tar.gz

[apple/icu.git] / icuSources / common / unicode / brkiter.h

diff --git a/icuSources/common/unicode/brkiter.h b/icuSources/common/unicode/brkiter.h
index 7df5f14083881771db8dc20bef14f4dfb7a6dbb5..dd9d4e23db163581d571a4ed25da7554b4c58ab8 100644 (file)
--- a/icuSources/common/unicode/brkiter.h
+++ b/icuSources/common/unicode/brkiter.h
@@ -1,6 +1,6 @@
 /*
 ********************************************************************************
 /*
 ********************************************************************************

-*   Copyright (C) 1997-2007, International Business Machines
+*   Copyright (C) 1997-2013, International Business Machines

 *   Corporation and others.  All Rights Reserved.
 ********************************************************************************
 *
 *   Corporation and others.  All Rights Reserved.
 ********************************************************************************
 *


@@ -91,10 +91,10 @@ U_NAMESPACE_BEGIN
  * plain C API with equivalent functionality is defined in the
  * file ubrk.h
  * <p>
  * plain C API with equivalent functionality is defined in the
  * file ubrk.h
  * <p>

- * Code snippits illustrating the use of the Break Iterator APIs
+ * Code snippets illustrating the use of the Break Iterator APIs

  * are available in the ICU User Guide,
  * http://icu-project.org/userguide/boundaryAnalysis.html
  * are available in the ICU User Guide,
  * http://icu-project.org/userguide/boundaryAnalysis.html

- * and in the sample program icu/source/samples/break/break.cpp"
+ * and in the sample program icu/source/samples/break/break.cpp

  *
  */
 class U_COMMON_API BreakIterator : public UObject {
  *
  */
 class U_COMMON_API BreakIterator : public UObject {


@@ -182,6 +182,11 @@ public:
      * Utext that was passed as a parameter, but that the underlying text itself
      * must not be altered while being referenced by the break iterator.
      *
      * Utext that was passed as a parameter, but that the underlying text itself
      * must not be altered while being referenced by the break iterator.
      *

+     * All index positions returned by break iterator functions are
+     * native indices from the UText. For example, when breaking UTF-8
+     * encoded text, the break positions returned by next(), previous(), etc.
+     * will be UTF-8 string indices, not UTF-16 positions.
+     *

      * @param text The UText used to change the text.
      * @param status receives any error codes.
      * @stable ICU 3.4
      * @param text The UText used to change the text.
      * @param status receives any error codes.
      * @stable ICU 3.4


@@ -208,19 +213,21 @@ public:
     };
 
     /**
     };
 
     /**

-     * Return the index of the first character in the text being scanned.
+     * Set the iterator position to the index of the first character in the text being scanned.
+     * @return The index of the first character in the text being scanned.

      * @stable ICU 2.0
      */
     virtual int32_t first(void) = 0;
 
     /**
      * @stable ICU 2.0
      */
     virtual int32_t first(void) = 0;
 
     /**

-     * Return the index immediately BEYOND the last character in the text being scanned.
+     * Set the iterator position to the index immediately BEYOND the last character in the text being scanned.
+     * @return The index immediately BEYOND the last character in the text being scanned.

      * @stable ICU 2.0
      */
     virtual int32_t last(void) = 0;
 
     /**
      * @stable ICU 2.0
      */
     virtual int32_t last(void) = 0;
 
     /**

-     * Return the boundary preceding the current boundary.
+     * Set the iterator position to the boundary preceding the current boundary.

      * @return The character index of the previous text boundary or DONE if all
      * boundaries have been returned.
      * @stable ICU 2.0
      * @return The character index of the previous text boundary or DONE if all
      * boundaries have been returned.
      * @stable ICU 2.0


@@ -228,7 +235,7 @@ public:
     virtual int32_t previous(void) = 0;
 
     /**
     virtual int32_t previous(void) = 0;
 
     /**

-     * Return the boundary following the current boundary.
+     * Advance the iterator to the boundary following the current boundary.

      * @return The character index of the next text boundary or DONE if all
      * boundaries have been returned.
      * @stable ICU 2.0
      * @return The character index of the next text boundary or DONE if all
      * boundaries have been returned.
      * @stable ICU 2.0


@@ -243,7 +250,7 @@ public:
     virtual int32_t current(void) const = 0;
 
     /**
     virtual int32_t current(void) const = 0;
 
     /**

-     * Return the first boundary following the specified offset.
+     * Advance the iterator to the first boundary following the specified offset.

      * The value returned is always greater than the offset or
      * the value BreakIterator.DONE
      * @param offset the offset to begin scanning.
      * The value returned is always greater than the offset or
      * the value BreakIterator.DONE
      * @param offset the offset to begin scanning.


@@ -253,7 +260,7 @@ public:
     virtual int32_t following(int32_t offset) = 0;
 
     /**
     virtual int32_t following(int32_t offset) = 0;
 
     /**

-     * Return the first boundary preceding the specified offset.
+     * Set the iterator position to the first boundary preceding the specified offset.

      * The value returned is always smaller than the offset or
      * the value BreakIterator.DONE
      * @param offset the offset to begin scanning.
      * The value returned is always smaller than the offset or
      * the value BreakIterator.DONE
      * @param offset the offset to begin scanning.


@@ -273,11 +280,11 @@ public:
     virtual UBool isBoundary(int32_t offset) = 0;
 
     /**
     virtual UBool isBoundary(int32_t offset) = 0;
 
     /**

-     * Return the nth boundary from the current boundary
-     * @param n which boundary to return.  A value of 0
+     * Set the iterator position to the nth boundary from the current boundary
+     * @param n the number of boundaries to move by.  A value of 0

      * does nothing.  Negative values move to previous boundaries
      * and positive values move to later boundaries.
      * does nothing.  Negative values move to previous boundaries
      * and positive values move to later boundaries.

-     * @return The index of the nth boundary from the current position, or
+     * @return The new iterator position, or

      * DONE if there are fewer than |n| boundaries in the specfied direction.
      * @stable ICU 2.0
      */
      * DONE if there are fewer than |n| boundaries in the specfied direction.
      * @stable ICU 2.0
      */


@@ -506,6 +513,7 @@ public:
      */
     Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const;
 
      */
     Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const;
 

+#ifndef U_HIDE_INTERNAL_API

     /** Get the locale for this break iterator object. You can choose between valid and actual locale.
      *  @param type type of the locale we're looking for (valid or actual)
      *  @param status error code for the operation
     /** Get the locale for this break iterator object. You can choose between valid and actual locale.
      *  @param type type of the locale we're looking for (valid or actual)
      *  @param status error code for the operation


@@ -513,6 +521,34 @@ public:
      *  @internal
      */
     const char *getLocaleID(ULocDataLocaleType type, UErrorCode& status) const;
      *  @internal
      */
     const char *getLocaleID(ULocDataLocaleType type, UErrorCode& status) const;

+#endif  /* U_HIDE_INTERNAL_API */
+
+    /**
+     *  Set the subject text string upon which the break iterator is operating
+     *  without changing any other aspect of the matching state.
+     *  The new and previous text strings must have the same content.
+     *
+     *  This function is intended for use in environments where ICU is operating on
+     *  strings that may move around in memory.  It provides a mechanism for notifying
+     *  ICU that the string has been relocated, and providing a new UText to access the
+     *  string in its new position.
+     *
+     *  Note that the break iterator implementation never copies the underlying text
+     *  of a string being processed, but always operates directly on the original text
+     *  provided by the user. Refreshing simply drops the references to the old text
+     *  and replaces them with references to the new.
+     *
+     *  Caution:  this function is normally used only by very specialized,
+     *  system-level code.  One example use case is with garbage collection that moves
+     *  the text in memory.
+     *
+     * @param input      The new (moved) text string.
+     * @param status     Receives errors detected by this function.
+     * @return           *this
+     *
+     * @stable ICU 49
+     */
+    virtual BreakIterator &refreshInputText(UText *input, UErrorCode &status) = 0;

 
  private:
     static BreakIterator* buildInstance(const Locale& loc, const char *type, int32_t kind, UErrorCode& status);
 
  private:
     static BreakIterator* buildInstance(const Locale& loc, const char *type, int32_t kind, UErrorCode& status);


@@ -523,6 +559,8 @@ public:
     friend class ICUBreakIteratorService;
 
 protected:
     friend class ICUBreakIteratorService;
 
 protected:

+    // Do not enclose protected default/copy constructors with #ifndef U_HIDE_INTERNAL_API
+    // or else the compiler will create a public ones.

     /** @internal */
     BreakIterator();
     /** @internal */
     /** @internal */
     BreakIterator();
     /** @internal */