1 /*

     2 * Copyright (C) 1996-2004, International Business Machines Corporation and others. All Rights Reserved.

     3 *****************************************************************************************

     4 */

     5 

     6 #ifndef UBRK_H

     7 #define UBRK_H

     8 

     9 #include "unicode/utypes.h"

    10 #include "unicode/uloc.h"

    11 

    12 /**

    13  * A text-break iterator.

    14  *  For usage in C programs.

    15  */

    16 #ifndef UBRK_TYPEDEF_UBREAK_ITERATOR

    17 #   define UBRK_TYPEDEF_UBREAK_ITERATOR

    18     /**

    19      *  Opaque type representing an ICU Break iterator object.

    20      *  @stable ICU 2.0

    21      */

    22     typedef void UBreakIterator;

    23 #endif

    24 

    25 #if !UCONFIG_NO_BREAK_ITERATION

    26 

    27 #include "unicode/parseerr.h"

    28 

    29 /**

    30  * \file

    31  * \brief C API: BreakIterator

    32  *

    33  * <h2> BreakIterator C API </h2>

    34  *

    35  * The BreakIterator C API defines  methods for finding the location

    36  * of boundaries in text. Pointer to a UBreakIterator maintain a

    37  * current position and scan over text returning the index of characters

    38  * where boundaries occur.

    39  * <P>

    40  * Line boundary analysis determines where a text string can be broken

    41  * when line-wrapping. The mechanism correctly handles punctuation and

    42  * hyphenated words.

    43  * <P>

    44  * Sentence boundary analysis allows selection with correct

    45  * interpretation of periods within numbers and abbreviations, and

    46  * trailing punctuation marks such as quotation marks and parentheses.

    47  * <P>

    48  * Word boundary analysis is used by search and replace functions, as

    49  * well as within text editing applications that allow the user to

    50  * select words with a double click. Word selection provides correct

    51  * interpretation of punctuation marks within and following

    52  * words. Characters that are not part of a word, such as symbols or

    53  * punctuation marks, have word-breaks on both sides.

    54  * <P>

    55  * Character boundary analysis allows users to interact with

    56  * characters as they expect to, for example, when moving the cursor

    57  * through a text string. Character boundary analysis provides correct

    58  * navigation of through character strings, regardless of how the

    59  * character is stored.  For example, an accented character might be

    60  * stored as a base character and a diacritical mark. What users

    61  * consider to be a character can differ between languages.

    62  * <P>

    63  * Title boundary analysis locates all positions,

    64  * typically starts of words, that should be set to Title Case

    65  * when title casing the text.

    66  * <P>

    67  *

    68  * This is the interface for all text boundaries.

    69  * <P>

    70  * Examples:

    71  * <P>

    72  * Helper function to output text

    73  * <pre>

    74  * \code

    75  *    void printTextRange(UChar* str, int32_t start, int32_t end ) {

    76  *         UChar* result;

    77  *         UChar* temp;

    78  *         const char* res;

    79  *         temp=(UChar*)malloc(sizeof(UChar) * ((u_strlen(str)-start)+1));

    80  *         result=(UChar*)malloc(sizeof(UChar) * ((end-start)+1));

    81  *         u_strcpy(temp, &str[start]);

    82  *         u_strncpy(result, temp, end-start);

    83  *         res=(char*)malloc(sizeof(char) * (u_strlen(result)+1));

    84  *         u_austrcpy(res, result);

    85  *         printf("%s\n", res);

    86  *    }

    87  * \endcode

    88  * </pre>

    89  * Print each element in order:

    90  * <pre>

    91  * \code

    92  *    void printEachForward( UBreakIterator* boundary, UChar* str) {

    93  *       int32_t end;

    94  *       int32_t start = ubrk_first(boundary);

    95  *       for (end = ubrk_next(boundary)); end != UBRK_DONE; start = end, end = ubrk_next(boundary)) {

    96  *             printTextRange(str, start, end );

    97  *         }

    98  *    }

    99  * \endcode

   100  * </pre>

   101  * Print each element in reverse order:

   102  * <pre>

   103  * \code

   104  *    void printEachBackward( UBreakIterator* boundary, UChar* str) {

   105  *       int32_t start;

   106  *       int32_t end = ubrk_last(boundary);

   107  *       for (start = ubrk_previous(boundary); start != UBRK_DONE;  end = start, start =ubrk_previous(boundary)) {

   108  *             printTextRange( str, start, end );

   109  *         }

   110  *    }

   111  * \endcode

   112  * </pre>

   113  * Print first element

   114  * <pre>

   115  * \code

   116  *    void printFirst(UBreakIterator* boundary, UChar* str) {

   117  *        int32_t end;

   118  *        int32_t start = ubrk_first(boundary);

   119  *        end = ubrk_next(boundary);

   120  *        printTextRange( str, start, end );

   121  *    }

   122  * \endcode

   123  * </pre>

   124  * Print last element

   125  * <pre>

   126  * \code

   127  *    void printLast(UBreakIterator* boundary, UChar* str) {

   128  *        int32_t start;

   129  *        int32_t end = ubrk_last(boundary);

   130  *        start = ubrk_previous(boundary);

   131  *        printTextRange(str, start, end );

   132  *    }

   133  * \endcode

   134  * </pre>

   135  * Print the element at a specified position

   136  * <pre>

   137  * \code

   138  *    void printAt(UBreakIterator* boundary, int32_t pos , UChar* str) {

   139  *        int32_t start;

   140  *        int32_t end = ubrk_following(boundary, pos);

   141  *        start = ubrk_previous(boundary);

   142  *        printTextRange(str, start, end );

   143  *    }

   144  * \endcode

   145  * </pre>

   146  * Creating and using text boundaries

   147  * <pre>

   148  * \code

   149  *       void BreakIterator_Example( void ) {

   150  *           UBreakIterator* boundary;

   151  *           UChar *stringToExamine;

   152  *           stringToExamine=(UChar*)malloc(sizeof(UChar) * (strlen("Aaa bbb ccc. Ddd eee fff.")+1) );

   153  *           u_uastrcpy(stringToExamine, "Aaa bbb ccc. Ddd eee fff.");

   154  *           printf("Examining: "Aaa bbb ccc. Ddd eee fff.");

   155  *

   156  *           //print each sentence in forward and reverse order

   157  *           boundary = ubrk_open(UBRK_SENTENCE, "en_us", stringToExamine, u_strlen(stringToExamine), &status);

   158  *           printf("----- forward: -----------\n");

   159  *           printEachForward(boundary, stringToExamine);

   160  *           printf("----- backward: ----------\n");

   161  *           printEachBackward(boundary, stringToExamine);

   162  *           ubrk_close(boundary);

   163  *

   164  *           //print each word in order

   165  *           boundary = ubrk_open(UBRK_WORD, "en_us", stringToExamine, u_strlen(stringToExamine), &status);

   166  *           printf("----- forward: -----------\n");

   167  *           printEachForward(boundary, stringToExamine);

   168  *           printf("----- backward: ----------\n");

   169  *           printEachBackward(boundary, stringToExamine);

   170  *           //print first element

   171  *           printf("----- first: -------------\n");

   172  *           printFirst(boundary, stringToExamine);

   173  *           //print last element

   174  *           printf("----- last: --------------\n");

   175  *           printLast(boundary, stringToExamine);

   176  *           //print word at charpos 10

   177  *           printf("----- at pos 10: ---------\n");

   178  *           printAt(boundary, 10 , stringToExamine);

   179  *

   180  *           ubrk_close(boundary);

   181  *       }

   182  * \endcode

   183  * </pre>

   184  */

   185 

   186 /** The possible types of text boundaries.  @stable ICU 2.0 */

   187 typedef enum UBreakIteratorType {

   188   /** Character breaks  @stable ICU 2.0 */

   189   UBRK_CHARACTER,

   190   /** Word breaks @stable ICU 2.0 */

   191   UBRK_WORD,

   192   /** Line breaks @stable ICU 2.0 */

   193   UBRK_LINE,

   194   /** Sentence breaks @stable ICU 2.0 */

   195   UBRK_SENTENCE,

   196 

   197 #ifndef U_HIDE_DEPRECATED_API

   198   /** 

   199    * Title Case breaks 

   200    * The iterator created using this type locates title boundaries as described for 

   201    * Unicode 3.2 only. For Unicode 4.0 and above title boundary iteration,

   202    * please use Word Boundary iterator.

   203    *

   204    * @deprecated ICU 2.8 Use the word break iterator for titlecasing for Unicode 4 and later.

   205    */

   206   UBRK_TITLE

   207 #endif /* U_HIDE_DEPRECATED_API */

   208 

   209 } UBreakIteratorType;

   210 

   211 /** Value indicating all text boundaries have been returned.

   212  *  @stable ICU 2.0 

   213  */

   214 #define UBRK_DONE ((int32_t) -1)

   215 

   216 

   217 /**

   218  *  Enum constants for the word break tags returned by

   219  *  getRuleStatus().  A range of values is defined for each category of

   220  *  word, to allow for further subdivisions of a category in future releases.

   221  *  Applications should check for tag values falling within the range, rather

   222  *  than for single individual values.

   223  *  @stable ICU 2.2

   224 */

   225 typedef enum UWordBreak {

   226     /** Tag value for "words" that do not fit into any of other categories. 

   227      *  Includes spaces and most punctuation. */

   228     UBRK_WORD_NONE           = 0,

   229     /** Upper bound for tags for uncategorized words. */

   230     UBRK_WORD_NONE_LIMIT     = 100,

   231     /** Tag value for words that appear to be numbers, lower limit.    */

   232     UBRK_WORD_NUMBER         = 100,

   233     /** Tag value for words that appear to be numbers, upper limit.    */

   234     UBRK_WORD_NUMBER_LIMIT   = 200,

   235     /** Tag value for words that contain letters, excluding

   236      *  hiragana, katakana or ideographic characters, lower limit.    */

   237     UBRK_WORD_LETTER         = 200,

   238     /** Tag value for words containing letters, upper limit  */

   239     UBRK_WORD_LETTER_LIMIT   = 300,

   240     /** Tag value for words containing kana characters, lower limit */

   241     UBRK_WORD_KANA           = 300,

   242     /** Tag value for words containing kana characters, upper limit */

   243     UBRK_WORD_KANA_LIMIT     = 400,

   244     /** Tag value for words containing ideographic characters, lower limit */

   245     UBRK_WORD_IDEO           = 400,

   246     /** Tag value for words containing ideographic characters, upper limit */

   247     UBRK_WORD_IDEO_LIMIT     = 500

   248 } UWordBreak;

   249 

   250 /**

   251  *  Enum constants for the line break tags returned by getRuleStatus().

   252  *  A range of values is defined for each category of

   253  *  word, to allow for further subdivisions of a category in future releases.

   254  *  Applications should check for tag values falling within the range, rather

   255  *  than for single individual values.

   256  *  @draft ICU 2.8

   257 */

   258 typedef enum ULineBreakTag {

   259     /** Tag value for soft line breaks, positions at which a line break

   260       *  is acceptable but not required                */

   261     UBRK_LINE_SOFT            = 0,

   262     /** Upper bound for soft line breaks.              */

   263     UBRK_LINE_SOFT_LIMIT      = 100,

   264     /** Tag value for a hard, or mandatory line break  */

   265     UBRK_LINE_HARD            = 100,

   266     /** Upper bound for hard line breaks.              */

   267     UBRK_LINE_HARD_LIMIT      = 200

   268 } ULineBreakTag;

   269 

   270 

   271 

   272 /**

   273  *  Enum constants for the sentence break tags returned by getRuleStatus().

   274  *  A range of values is defined for each category of

   275  *  sentence, to allow for further subdivisions of a category in future releases.

   276  *  Applications should check for tag values falling within the range, rather

   277  *  than for single individual values.

   278  *  @draft ICU 2.8

   279 */

   280 typedef enum USentenceBreakTag {

   281     /** Tag value for for sentences  ending with a sentence terminator

   282       * ('.', '?', '!', etc.) character, possibly followed by a

   283       * hard separator (CR, LF, PS, etc.)

   284       */

   285     UBRK_SENTENCE_TERM       = 0,

   286     /** Upper bound for tags for sentences ended by sentence terminators.    */

   287     UBRK_SENTENCE_TERM_LIMIT = 100,

   288     /** Tag value for for sentences that do not contain an ending

   289       * sentence terminator ('.', '?', '!', etc.) character, but 

   290       * are ended only by a hard separator (CR, LF, PS, etc.) or end of input.

   291       */

   292     UBRK_SENTENCE_SEP        = 100,

   293     /** Upper bound for tags for sentences ended by a separator.              */

   294     UBRK_SENTENCE_SEP_LIMIT  = 200

   295     /** Tag value for a hard, or mandatory line break  */

   296 } USentenceBreakTag;

   297 

   298 

   299 /**

   300  * Open a new UBreakIterator for locating text boundaries for a specified locale.

   301  * A UBreakIterator may be used for detecting character, line, word,

   302  * and sentence breaks in text.

   303  * @param type The type of UBreakIterator to open: one of UBRK_CHARACTER, UBRK_WORD,

   304  * UBRK_LINE, UBRK_SENTENCE

   305  * @param locale The locale specifying the text-breaking conventions.

   306  * @param text The text to be iterated over.

   307  * @param textLength The number of characters in text, or -1 if null-terminated.

   308  * @param status A UErrorCode to receive any errors.

   309  * @return A UBreakIterator for the specified locale.

   310  * @see ubrk_openRules

   311  * @stable ICU 2.0

   312  */

   313 U_STABLE UBreakIterator* U_EXPORT2

   314 ubrk_open(UBreakIteratorType type,

   315       const char *locale,

   316       const UChar *text,

   317       int32_t textLength,

   318       UErrorCode *status);

   319 

   320 /**

   321  * Open a new UBreakIterator for locating text boundaries using specified breaking rules.

   322  * The rule syntax is ... (TBD)

   323  * @param rules A set of rules specifying the text breaking conventions.

   324  * @param rulesLength The number of characters in rules, or -1 if null-terminated.

   325  * @param text The text to be iterated over.  May be null, in which case ubrk_setText() is

   326  *        used to specify the text to be iterated.

   327  * @param textLength The number of characters in text, or -1 if null-terminated.

   328  * @param parseErr   Receives position and context information for any syntax errors

   329  *                   detected while parsing the rules.

   330  * @param status A UErrorCode to receive any errors.

   331  * @return A UBreakIterator for the specified rules.

   332  * @see ubrk_open

   333  * @stable ICU 2.2

   334  */

   335 U_STABLE UBreakIterator* U_EXPORT2

   336 ubrk_openRules(const UChar     *rules,

   337                int32_t         rulesLength,

   338                const UChar     *text,

   339                int32_t          textLength,

   340                UParseError     *parseErr,

   341                UErrorCode      *status);

   342 

   343 /**

   344  * Thread safe cloning operation

   345  * @param bi iterator to be cloned

   346  * @param stackBuffer user allocated space for the new clone. If NULL new memory will be allocated.

   347  *  If buffer is not large enough, new memory will be allocated.

   348  *  Clients can use the U_BRK_SAFECLONE_BUFFERSIZE. This will probably be enough to avoid memory allocations.

   349  * @param pBufferSize pointer to size of allocated space.

   350  *  If *pBufferSize == 0, a sufficient size for use in cloning will

   351  *  be returned ('pre-flighting')

   352  *  If *pBufferSize is not enough for a stack-based safe clone,

   353  *  new memory will be allocated.

   354  * @param status to indicate whether the operation went on smoothly or there were errors

   355  *  An informational status value, U_SAFECLONE_ALLOCATED_ERROR, is used if any allocations were necessary.

   356  * @return pointer to the new clone

   357  * @stable ICU 2.0

   358  */

   359 U_STABLE UBreakIterator * U_EXPORT2

   360 ubrk_safeClone(

   361           const UBreakIterator *bi,

   362           void *stackBuffer,

   363           int32_t *pBufferSize,

   364           UErrorCode *status);

   365 

   366 /**

   367   * A recommended size (in bytes) for the memory buffer to be passed to ubrk_saveClone().

   368   * @stable ICU 2.0

   369   */

   370 #define U_BRK_SAFECLONE_BUFFERSIZE 512

   371 

   372 /**

   373 * Close a UBreakIterator.

   374 * Once closed, a UBreakIterator may no longer be used.

   375 * @param bi The break iterator to close.

   376  * @stable ICU 2.0

   377 */

   378 U_STABLE void U_EXPORT2

   379 ubrk_close(UBreakIterator *bi);

   380 

   381 /**

   382  * Sets an existing iterator to point to a new piece of text

   383  * @param bi The iterator to use

   384  * @param text The text to be set

   385  * @param textLength The length of the text

   386  * @param status The error code

   387  * @stable ICU 2.0

   388  */

   389 U_STABLE void U_EXPORT2

   390 ubrk_setText(UBreakIterator* bi,

   391              const UChar*    text,

   392              int32_t         textLength,

   393              UErrorCode*     status);

   394 

   395 /**

   396  * Determine the most recently-returned text boundary.

   397  *

   398  * @param bi The break iterator to use.

   399  * @return The character index most recently returned by \ref ubrk_next, \ref ubrk_previous,

   400  * \ref ubrk_first, or \ref ubrk_last.

   401  * @stable ICU 2.0

   402  */

   403 U_STABLE int32_t U_EXPORT2

   404 ubrk_current(const UBreakIterator *bi);

   405 

   406 /**

   407  * Determine the text boundary following the current text boundary.

   408  *

   409  * @param bi The break iterator to use.

   410  * @return The character index of the next text boundary, or UBRK_DONE

   411  * if all text boundaries have been returned.

   412  * @see ubrk_previous

   413  * @stable ICU 2.0

   414  */

   415 U_STABLE int32_t U_EXPORT2

   416 ubrk_next(UBreakIterator *bi);

   417 

   418 /**

   419  * Determine the text boundary preceding the current text boundary.

   420  *

   421  * @param bi The break iterator to use.

   422  * @return The character index of the preceding text boundary, or UBRK_DONE

   423  * if all text boundaries have been returned.

   424  * @see ubrk_next

   425  * @stable ICU 2.0

   426  */

   427 U_STABLE int32_t U_EXPORT2

   428 ubrk_previous(UBreakIterator *bi);

   429 

   430 /**

   431  * Determine the index of the first character in the text being scanned.

   432  * This is not always the same as index 0 of the text.

   433  * @param bi The break iterator to use.

   434  * @return The character index of the first character in the text being scanned.

   435  * @see ubrk_last

   436  * @stable ICU 2.0

   437  */

   438 U_STABLE int32_t U_EXPORT2

   439 ubrk_first(UBreakIterator *bi);

   440 

   441 /**

   442  * Determine the index immediately <EM>beyond</EM> the last character in the text being

   443  * scanned.

   444  * This is not the same as the last character.

   445  * @param bi The break iterator to use.

   446  * @return The character offset immediately <EM>beyond</EM> the last character in the

   447  * text being scanned.

   448  * @see ubrk_first

   449  * @stable ICU 2.0

   450  */

   451 U_STABLE int32_t U_EXPORT2

   452 ubrk_last(UBreakIterator *bi);

   453 

   454 /**

   455  * Determine the text boundary preceding the specified offset.

   456  * The value returned is always smaller than offset, or UBRK_DONE.

   457  * @param bi The break iterator to use.

   458  * @param offset The offset to begin scanning.

   459  * @return The text boundary preceding offset, or UBRK_DONE.

   460  * @see ubrk_following

   461  * @stable ICU 2.0

   462  */

   463 U_STABLE int32_t U_EXPORT2

   464 ubrk_preceding(UBreakIterator *bi,

   465            int32_t offset);

   466 

   467 /**

   468  * Determine the text boundary following the specified offset.

   469  * The value returned is always greater than offset, or UBRK_DONE.

   470  * @param bi The break iterator to use.

   471  * @param offset The offset to begin scanning.

   472  * @return The text boundary following offset, or UBRK_DONE.

   473  * @see ubrk_preceding

   474  * @stable ICU 2.0

   475  */

   476 U_STABLE int32_t U_EXPORT2

   477 ubrk_following(UBreakIterator *bi,

   478            int32_t offset);

   479 

   480 /**

   481 * Get a locale for which text breaking information is available.

   482 * A UBreakIterator in a locale returned by this function will perform the correct

   483 * text breaking for the locale.

   484 * @param index The index of the desired locale.

   485 * @return A locale for which number text breaking information is available, or 0 if none.

   486 * @see ubrk_countAvailable

   487 * @stable ICU 2.0

   488 */

   489 U_STABLE const char* U_EXPORT2

   490 ubrk_getAvailable(int32_t index);

   491 

   492 /**

   493 * Determine how many locales have text breaking information available.

   494 * This function is most useful as determining the loop ending condition for

   495 * calls to \ref ubrk_getAvailable.

   496 * @return The number of locales for which text breaking information is available.

   497 * @see ubrk_getAvailable

   498 * @stable ICU 2.0

   499 */

   500 U_STABLE int32_t U_EXPORT2

   501 ubrk_countAvailable(void);

   502 

   503 

   504 /**

   505 * Returns true if the specfied position is a boundary position.  As a side

   506 * effect, leaves the iterator pointing to the first boundary position at

   507 * or after "offset".

   508 * @param bi The break iterator to use.

   509 * @param offset the offset to check.

   510 * @return True if "offset" is a boundary position.

   511 * @stable ICU 2.0

   512 */

   513 U_STABLE  UBool U_EXPORT2

   514 ubrk_isBoundary(UBreakIterator *bi, int32_t offset);

   515 

   516 /**

   517  * Return the status from the break rule that determined the most recently

   518  * returned break position.  The values appear in the rule source

   519  * within brackets, {123}, for example.  For rules that do not specify a

   520  * status, a default value of 0 is returned.

   521  * <p>

   522  * For word break iterators, the possible values are defined in enum UWordBreak.

   523  * @stable ICU 2.2

   524  */

   525 U_STABLE  int32_t U_EXPORT2

   526 ubrk_getRuleStatus(UBreakIterator *bi);

   527 

   528 /**

   529  * Get the statuses from the break rules that determined the most recently

   530  * returned break position.  The values appear in the rule source

   531  * within brackets, {123}, for example.  The default status value for rules

   532  * that do not explicitly provide one is zero.

   533  * <p>

   534  * For word break iterators, the possible values are defined in enum UWordBreak.

   535  * @param bi        The break iterator to use

   536  * @param fillInVec an array to be filled in with the status values.  

   537  * @param capacity  the length of the supplied vector.  A length of zero causes

   538  *                  the function to return the number of status values, in the

   539  *                  normal way, without attemtping to store any values.

   540  * @param status    receives error codes.  

   541  * @return          The number of rule status values from rules that determined 

   542  *                  the most recent boundary returned by the break iterator.

   543  * @draft ICU 3.0

   544  */

   545 U_DRAFT  int32_t U_EXPORT2

   546 ubrk_getRuleStatusVec(UBreakIterator *bi, int32_t *fillInVec, int32_t capacity, UErrorCode *status);

   547 

   548 /**

   549  * Return the locale of the break iterator. You can choose between the valid and

   550  * the actual locale.

   551  * @param bi break iterator

   552  * @param type locale type (valid or actual)

   553  * @param status error code

   554  * @return locale string

   555  * @draft ICU 2.8 likely to change in ICU 3.0, based on feedback

   556  */

   557 U_DRAFT const char* U_EXPORT2

   558 ubrk_getLocaleByType(const UBreakIterator *bi, ULocDataLocaleType type, UErrorCode* status);

   559 

   560 

   561 #endif /* #if !UCONFIG_NO_BREAK_ITERATION */

   562 

   563 #endif