ICU-59180.0.1.tar.gz

[apple/icu.git] / icuSources / i18n / unicode / search.h

diff --git a/icuSources/i18n/unicode/search.h b/icuSources/i18n/unicode/search.h
index 16b990e13cbe93b5d92270019ab5d88f8e282d95..403d3c5a914b80e5f02a4eace986cfee15435035 100644 (file)
--- a/icuSources/i18n/unicode/search.h
+++ b/icuSources/i18n/unicode/search.h
@@ -1,6 +1,8 @@
+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 **********************************************************************
-*   Copyright (C) 2001 IBM and others. All rights reserved.
+*   Copyright (C) 2001-2011 IBM and others. All rights reserved.
 **********************************************************************
 *   Date        Name        Description
 *  03/22/2000   helena      Creation.
@@ -12,7 +14,12 @@
 
 #include "unicode/utypes.h"
 
-#if !UCONFIG_NO_COLLATION
+/**
+ * \file 
+ * \brief C++ API: SearchIterator object.
+ */
+ 
+#if !UCONFIG_NO_COLLATION && !UCONFIG_NO_BREAK_ITERATION
 
 #include "unicode/uobject.h"
 #include "unicode/unistr.h"
@@ -29,9 +36,11 @@ struct USearch;
 */
 typedef struct USearch USearch;
 
+#if U_SHOW_CPLUSPLUS_API
 U_NAMESPACE_BEGIN
 
 /**
+ *
  * <tt>SearchIterator</tt> is an abstract base class that provides 
  * methods to search for a pattern within a text string. Instances of
  * <tt>SearchIterator</tt> maintain a current position and scans over the 
@@ -100,7 +109,7 @@ public:
      * string accordingly without checking if the index is pointing to a 
      * valid starting point to begin searching. 
      * @param position within the text to be set. If position is less
-     *                         than or greater than the text range for searching, 
+     *             than or greater than the text range for searching, 
      *          an U_INDEX_OUTOFBOUNDS_ERROR will be returned
      * @param status for errors if it occurs
      * @stable ICU 2.0
@@ -300,14 +309,14 @@ public:
     int32_t first(UErrorCode &status);
 
     /**
-     * Returns the first index greater than <tt>position</tt> at which the 
+     * Returns the first index equal or greater than <tt>position</tt> at which the 
      * string text matches the search pattern. The iterator is adjusted so 
      * that its current index (as returned by <tt>getOffset</tt>) is the 
-     * match position if one was found. If a match is not found, 
-     * <tt>USEARCH_DONE</tt> will be returned and the iterator will be 
-     * adjusted to the index USEARCH_DONE
+     * match position if one was found.
+     * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and the
+     * iterator will be adjusted to the index <tt>USEARCH_DONE</tt>.
      * @param  position where search if to start from. If position is less
-     *                         than or greater than the text range for searching, 
+     *             than or greater than the text range for searching, 
      *          an U_INDEX_OUTOFBOUNDS_ERROR will be returned
      * @param  status for errors if it occurs
      * @return The character index of the first match following 
@@ -340,8 +349,14 @@ public:
      * position if one was found. If a match is not found, 
      * <tt>USEARCH_DONE</tt> will be returned and the iterator will be 
      * adjusted to the index USEARCH_DONE
+     * <p>
+     * When <tt>USEARCH_OVERLAP</tt> option is off, the last index of the
+     * result match is always less than <tt>position</tt>.
+     * When <tt>USERARCH_OVERLAP</tt> is on, the result match may span across
+     * <tt>position</tt>.
+     *
      * @param  position where search is to start from. If position is less
-     *                         than or greater than the text range for searching, 
+     *             than or greater than the text range for searching, 
      *          an U_INDEX_OUTOFBOUNDS_ERROR will be returned
      * @param  status for errors if it occurs
      * @return The character index of the first match preceding 
@@ -440,7 +455,7 @@ protected:
      *                is <tt>NULL</tt>, no break detection is attempted.  
      * @see #handleNext
      * @see #handlePrev
-        * @stable ICU 2.0
+     * @stable ICU 2.0
      */
     SearchIterator(const UnicodeString &text, 
                          BreakIterator *breakiter = NULL);
@@ -462,7 +477,7 @@ protected:
      *                is <tt>NULL</tt>, no break detection is attempted.
      * @see #handleNext
      * @see #handlePrev
-        * @stable ICU 2.0
+     * @stable ICU 2.0
      */
     SearchIterator(CharacterIterator &text, BreakIterator *breakiter = NULL);
 
@@ -472,7 +487,7 @@ protected:
      * Assignment operator. Sets this iterator to have the same behavior,
      * and iterate over the same text, as the one passed in.
      * @param that instance to be copied.
-        * @stable ICU 2.0
+     * @stable ICU 2.0
      */
     SearchIterator & operator=(const SearchIterator &that);
 
@@ -493,7 +508,7 @@ protected:
      * @return index at which the match starts, else if match is not found 
      *         USEARCH_DONE is returned
      * @see #setMatchLength
-        * @stable ICU 2.0
+     * @stable ICU 2.0
      */
     virtual int32_t handleNext(int32_t position, UErrorCode &status) 
                                                                          = 0;
@@ -515,7 +530,7 @@ protected:
      * @return index at which the match starts, else if match is not found 
      *         USEARCH_DONE is returned
      * @see #setMatchLength
-        * @stable ICU 2.0
+     * @stable ICU 2.0
      */
      virtual int32_t handlePrev(int32_t position, UErrorCode &status) 
                                                                          = 0;
@@ -528,7 +543,7 @@ protected:
      * @param length length of the matched text.
      * @see #handleNext
      * @see #handlePrev
-        * @stable ICU 2.0
+     * @stable ICU 2.0
      */
     virtual void setMatchLength(int32_t length);
 
@@ -540,7 +555,7 @@ protected:
      * @param position start offset of the matched text.
      * @see #handleNext
      * @see #handlePrev
-        * @stable ICU 2.0
+     * @stable ICU 2.0
      */
     virtual void setMatchStart(int32_t position);
 
@@ -556,6 +571,7 @@ inline UBool SearchIterator::operator!=(const SearchIterator &that) const
    return !operator==(that); 
 }
 U_NAMESPACE_END
+#endif // U_SHOW_CPLUSPLUS_API
 
 #endif /* #if !UCONFIG_NO_COLLATION */