1 /*

     2 *******************************************************************************

     3 *

     4 *   Copyright (C) 2003, International Business Machines

     5 *   Corporation and others.  All Rights Reserved.

     6 *

     7 *******************************************************************************

     8 *   file name:  unorm_it.h

     9 *   encoding:   US-ASCII

    10 *   tab size:   8 (not used)

    11 *   indentation:4

    12 *

    13 *   created on: 2003jan21

    14 *   created by: Markus W. Scherer

    15 */

    16 

    17 #ifndef __UNORM_IT_H__

    18 #define __UNORM_IT_H__

    19 

    20 #include "unicode/utypes.h"

    21 

    22 #if !UCONFIG_NO_COLLATION && !UCONFIG_NO_NORMALIZATION

    23 

    24 #include "unicode/uiter.h"

    25 #include "unicode/unorm.h"

    26 

    27 /**

    28  * Normalizing UCharIterator wrapper.

    29  * This internal API basically duplicates the functionality of the C++ Normalizer

    30  * but

    31  * - it actually implements a character iterator (UCharIterator)

    32  *   with few restrictions (see unorm_setIter())

    33  * - it supports UCharIterator getState()/setState()

    34  * - it uses lower-level APIs and buffers more text and states,

    35  *   hopefully resulting in higher performance

    36  *

    37  * Usage example:

    38  * \code

    39  * function(UCharIterator *srcIter) {

    40  *     UNormIterator *uni;

    41  *     UCharIterator *iter;

    42  *     UErrorCode errorCode;

    43  * 

    44  *     errorCode=U_ZERO_ERROR;

    45  *     uni=unorm_openIter(&errorCode);

    46  *     if(U_FAILURE(errorCode)) {

    47  *         // report error

    48  *         return;

    49  *     }

    50  * 

    51  *     iter=unorm_setIter(uni, srcIter, UNORM_FCD, &errorCode);

    52  *     if(U_FAILURE(errorCode)) {

    53  *         // report error

    54  *     } else {

    55  *         // use iter to iterate over the canonically ordered

    56  *         // version of srcIter's text

    57  *         uint32_t state;

    58  * 

    59  *         ...

    60  * 

    61  *         state=uiter_getState(iter);

    62  *         if(state!=UITER_NO_STATE) {

    63  *             // use valid state, store it, use iter some more

    64  *             ...

    65  * 

    66  *             // later restore iter to the saved state:

    67  *             uiter_setState(iter, state, &errorCode);

    68  * 

    69  *             ...

    70  *         }

    71  * 

    72  *         ...

    73  *     }

    74  *     unorm_closeIter(uni);

    75  * }

    76  * \endcode

    77  *

    78  * See also the ICU test suites.

    79  *

    80  * @internal

    81  */

    82 struct UNormIterator;

    83 typedef struct UNormIterator UNormIterator;

    84 

    85 /**

    86  * Size of a stack buffer to hold a UNormIterator, see the stackMem parameter

    87  * of unorm_openIter().

    88  *

    89  * @internal

    90  */

    91 #define UNORM_ITER_SIZE 1024

    92 

    93 /**

    94  * Open a normalizing iterator. Must be closed later.

    95  * Use unorm_setIter().

    96  *

    97  * @param stackMem Pointer to preallocated (stack-allocated) buffer to hold

    98  *                 the UNormIterator if possible; can be NULL.

    99  * @param stackMemSize Number of bytes at stackMem; can be 0,

   100  *                     or should be >= UNORM_ITER_SIZE for a non-NULL stackMem.

   101  * @param pErrorCode ICU error code

   102  * @return an allocated and pre-initialized UNormIterator

   103  * @internal

   104  */

   105 U_CAPI UNormIterator * U_EXPORT2

   106 unorm_openIter(void *stackMem, int32_t stackMemSize, UErrorCode *pErrorCode);

   107 

   108 /**

   109  * Close a normalizing iterator.

   110  *

   111  * @param uni UNormIterator from unorm_openIter()

   112  * @internal

   113  */

   114 U_CAPI void U_EXPORT2

   115 unorm_closeIter(UNormIterator *uni);

   116 

   117 /**

   118  * Set a UCharIterator and a normalization mode for the normalizing iterator

   119  * to wrap. The normalizing iterator will read from the character iterator,

   120  * normalize the text, and in turn deliver it with its own wrapper UCharIterator

   121  * interface which it returns.

   122  *

   123  * The source iterator remains at its current position through the unorm_setIter()

   124  * call but will be used and moved as soon as the

   125  * the returned normalizing iterator is.

   126  *

   127  * The returned interface pointer is valid for as long as the normalizing iterator

   128  * is open and until another unorm_setIter() call is made on it.

   129  *

   130  * The normalizing iterator's UCharIterator interface has the following properties:

   131  * - getIndex() and move() will almost always return UITER_UNKNOWN_INDEX

   132  * - getState() will return UITER_NO_STATE for unknown states for positions

   133  *              that are not at normalization boundaries

   134  *

   135  * @param uni UNormIterator from unorm_openIter()

   136  * @param iter The source text UCharIterator to be wrapped. It is aliases into the normalizing iterator.

   137  *             Must support getState() and setState().

   138  * @param mode The normalization mode.

   139  * @param pErrorCode ICU error code

   140  * @return an alias to the normalizing iterator's UCharIterator interface

   141  * @internal

   142  */

   143 U_CAPI UCharIterator * U_EXPORT2

   144 unorm_setIter(UNormIterator *uni, UCharIterator *iter, UNormalizationMode mode, UErrorCode *pErrorCode);

   145 

   146 #endif /* uconfig.h switches */

   147 

   148 #endif