mirror of
https://github.com/unicode-org/icu.git
synced 2025-04-18 11:14:22 +00:00
ICU-9101 Cleaned up API doc for StringSearch. Removed clauses mentioning Boyer-Moore algorithm. Keep the docs synchronized with ICU4J StringSearch.
X-SVN-Rev: 35354
This commit is contained in:
Yoshito Umaoka
parent
5799b71849
commit
7202567040
1 changed files with 38 additions and 47 deletions
|
|
@ -30,85 +30,79 @@ U_NAMESPACE_BEGIN
|
|||
* <tt>StringSearch</tt> is a <tt>SearchIterator</tt> that provides
|
||||
* language-sensitive text searching based on the comparison rules defined
|
||||
* in a {@link RuleBasedCollator} object.
|
||||
* StringSearch ensures that language eccentricity can be
|
||||
* handled, e.g. for the German collator, characters ß and SS will be matched
|
||||
* StringSearch ensures that language eccentricity can be
|
||||
* handled, e.g. for the German collator, characters ß and SS will be matched
|
||||
* if case is chosen to be ignored.
|
||||
* See the <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/collation/ICU_collation_design.htm">
|
||||
* "ICU Collation Design Document"</a> for more information.
|
||||
* <p>
|
||||
* The algorithm implemented is a modified form of the Boyer Moore's search.
|
||||
* For more information see
|
||||
* <a href="http://icu-project.org/docs/papers/efficient_text_searching_in_java.html">
|
||||
* "Efficient Text Searching in Java"</a>, published in <i>Java Report</i>
|
||||
* in February, 1999, for further information on the algorithm.
|
||||
* <p>
|
||||
* There are 2 match options for selection:<br>
|
||||
* Let S' be the sub-string of a text string S between the offsets start and
|
||||
* end <start, end>.
|
||||
* Let S' be the sub-string of a text string S between the offsets start and
|
||||
* end [start, end].
|
||||
* <br>
|
||||
* A pattern string P matches a text string S at the offsets <start, end>
|
||||
* A pattern string P matches a text string S at the offsets [start, end]
|
||||
* if
|
||||
* <pre>
|
||||
* option 1. Some canonical equivalent of P matches some canonical equivalent
|
||||
* option 1. Some canonical equivalent of P matches some canonical equivalent
|
||||
* of S'
|
||||
* option 2. P matches S' and if P starts or ends with a combining mark,
|
||||
* there exists no non-ignorable combining mark before or after S?
|
||||
* in S respectively.
|
||||
* option 2. P matches S' and if P starts or ends with a combining mark,
|
||||
* there exists no non-ignorable combining mark before or after S?
|
||||
* in S respectively.
|
||||
* </pre>
|
||||
* Option 2. will be the default.
|
||||
* <p>
|
||||
* This search has APIs similar to that of other text iteration mechanisms
|
||||
* such as the break iterators in <tt>BreakIterator</tt>. Using these
|
||||
* APIs, it is easy to scan through text looking for all occurances of
|
||||
* APIs, it is easy to scan through text looking for all occurrences of
|
||||
* a given pattern. This search iterator allows changing of direction by
|
||||
* calling a <tt>reset</tt> followed by a <tt>next</tt> or <tt>previous</tt>.
|
||||
* Though a direction change can occur without calling <tt>reset</tt> first,
|
||||
* calling a <tt>reset</tt> followed by a <tt>next</tt> or <tt>previous</tt>.
|
||||
* Though a direction change can occur without calling <tt>reset</tt> first,
|
||||
* this operation comes with some speed penalty.
|
||||
* Match results in the forward direction will match the result matches in
|
||||
* Match results in the forward direction will match the result matches in
|
||||
* the backwards direction in the reverse order
|
||||
* <p>
|
||||
* <tt>SearchIterator</tt> provides APIs to specify the starting position
|
||||
* <tt>SearchIterator</tt> provides APIs to specify the starting position
|
||||
* within the text string to be searched, e.g. <tt>setOffset</tt>,
|
||||
* <tt>preceding</tt> and <tt>following</tt>. Since the
|
||||
* starting position will be set as it is specified, please take note that
|
||||
* there are some danger points which the search may render incorrect
|
||||
* <tt>preceding</tt> and <tt>following</tt>. Since the
|
||||
* starting position will be set as it is specified, please take note that
|
||||
* there are some danger points which the search may render incorrect
|
||||
* results:
|
||||
* <ul>
|
||||
* <li> The midst of a substring that requires normalization.
|
||||
* <li> If the following match is to be found, the position should not be the
|
||||
* second character which requires to be swapped with the preceding
|
||||
* character. Vice versa, if the preceding match is to be found,
|
||||
* position to search from should not be the first character which
|
||||
* second character which requires to be swapped with the preceding
|
||||
* character. Vice versa, if the preceding match is to be found,
|
||||
* position to search from should not be the first character which
|
||||
* requires to be swapped with the next character. E.g certain Thai and
|
||||
* Lao characters require swapping.
|
||||
* <li> If a following pattern match is to be found, any position within a
|
||||
* contracting sequence except the first will fail. Vice versa if a
|
||||
* preceding pattern match is to be found, a invalid starting point
|
||||
* <li> If a following pattern match is to be found, any position within a
|
||||
* contracting sequence except the first will fail. Vice versa if a
|
||||
* preceding pattern match is to be found, a invalid starting point
|
||||
* would be any character within a contracting sequence except the last.
|
||||
* </ul>
|
||||
* <p>
|
||||
* A breakiterator can be used if only matches at logical breaks are desired.
|
||||
* Using a breakiterator will only give you results that exactly matches the
|
||||
* A <tt>BreakIterator</tt> can be used if only matches at logical breaks are desired.
|
||||
* Using a <tt>BreakIterator</tt> will only give you results that exactly matches the
|
||||
* boundaries given by the breakiterator. For instance the pattern "e" will
|
||||
* not be found in the string "\u00e9" if a character break iterator is used.
|
||||
* <p>
|
||||
* Options are provided to handle overlapping matches.
|
||||
* E.g. In English, overlapping matches produces the result 0 and 2
|
||||
* for the pattern "abab" in the text "ababab", where else mutually
|
||||
* Options are provided to handle overlapping matches.
|
||||
* E.g. In English, overlapping matches produces the result 0 and 2
|
||||
* for the pattern "abab" in the text "ababab", where else mutually
|
||||
* exclusive matches only produce the result of 0.
|
||||
* <p>
|
||||
* Though collator attributes will be taken into consideration while
|
||||
* performing matches, there are no APIs here for setting and getting the
|
||||
* Though collator attributes will be taken into consideration while
|
||||
* performing matches, there are no APIs here for setting and getting the
|
||||
* attributes. These attributes can be set by getting the collator
|
||||
* from <tt>getCollator</tt> and using the APIs in <tt>coll.h</tt>.
|
||||
* Lastly to update StringSearch to the new collator attributes,
|
||||
* reset() has to be called.
|
||||
* Lastly to update <tt>StringSearch</tt> to the new collator attributes,
|
||||
* <tt>reset</tt> has to be called.
|
||||
* <p>
|
||||
* Restriction: <br>
|
||||
* Currently there are no composite characters that consists of a
|
||||
* character with combining class > 0 before a character with combining
|
||||
* class == 0. However, if such a character exists in the future,
|
||||
* StringSearch does not guarantee the results for option 1.
|
||||
* character with combining class > 0 before a character with combining
|
||||
* class == 0. However, if such a character exists in the future,
|
||||
* <tt>StringSearch</tt> does not guarantee the results for option 1.
|
||||
* <p>
|
||||
* Consult the <tt>SearchIterator</tt> documentation for information on
|
||||
* and examples of how to use instances of this class to implement text
|
||||
|
|
@ -128,7 +122,7 @@ U_NAMESPACE_BEGIN
|
|||
* }
|
||||
* </code></pre>
|
||||
* <p>
|
||||
* Note, StringSearch is not to be subclassed.
|
||||
* Note, <tt>StringSearch</tt> is not to be subclassed.
|
||||
* </p>
|
||||
* @see SearchIterator
|
||||
* @see RuleBasedCollator
|
||||
|
|
@ -372,9 +366,7 @@ public:
|
|||
/**
|
||||
* Sets the collator used for the language rules. User retains the
|
||||
* ownership of this collator, thus the responsibility of deletion lies
|
||||
* with the user. This method causes internal data such as Boyer-Moore
|
||||
* shift tables to be recalculated, but the iterator's position is
|
||||
* unchanged.
|
||||
* with the user. The iterator's position will not be changed by this method.
|
||||
* @param coll collator
|
||||
* @param status for errors if any
|
||||
* @stable ICU 2.0
|
||||
|
|
@ -383,8 +375,7 @@ public:
|
|||
|
||||
/**
|
||||
* Sets the pattern used for matching.
|
||||
* Internal data like the Boyer Moore table will be recalculated, but
|
||||
* the iterator's position is unchanged.
|
||||
* The iterator's position will not be changed by this method.
|
||||
* @param pattern search pattern to be found
|
||||
* @param status for errors if any. If the pattern length is 0 then an
|
||||
* U_ILLEGAL_ARGUMENT_ERROR is returned.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue