summaryrefslogtreecommitdiff
path: root/Build/source/libs/icu/icu-xetex/common/unorm_it.h
blob: 384b7d4469e5e800a424663d93accf7d31654d60 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
/*
*******************************************************************************
*
*   Copyright (C) 2003, International Business Machines
*   Corporation and others.  All Rights Reserved.
*
*******************************************************************************
*   file name:  unorm_it.h
*   encoding:   US-ASCII
*   tab size:   8 (not used)
*   indentation:4
*
*   created on: 2003jan21
*   created by: Markus W. Scherer
*/

#ifndef __UNORM_IT_H__
#define __UNORM_IT_H__

#include "unicode/utypes.h"

#if !UCONFIG_NO_COLLATION && !UCONFIG_NO_NORMALIZATION

#include "unicode/uiter.h"
#include "unicode/unorm.h"

/**
 * Normalizing UCharIterator wrapper.
 * This internal API basically duplicates the functionality of the C++ Normalizer
 * but
 * - it actually implements a character iterator (UCharIterator)
 *   with few restrictions (see unorm_setIter())
 * - it supports UCharIterator getState()/setState()
 * - it uses lower-level APIs and buffers more text and states,
 *   hopefully resulting in higher performance
 *
 * Usage example:
 * \code
 * function(UCharIterator *srcIter) {
 *     UNormIterator *uni;
 *     UCharIterator *iter;
 *     UErrorCode errorCode;
 * 
 *     errorCode=U_ZERO_ERROR;
 *     uni=unorm_openIter(&errorCode);
 *     if(U_FAILURE(errorCode)) {
 *         // report error
 *         return;
 *     }
 * 
 *     iter=unorm_setIter(uni, srcIter, UNORM_FCD, &errorCode);
 *     if(U_FAILURE(errorCode)) {
 *         // report error
 *     } else {
 *         // use iter to iterate over the canonically ordered
 *         // version of srcIter's text
 *         uint32_t state;
 * 
 *         ...
 * 
 *         state=uiter_getState(iter);
 *         if(state!=UITER_NO_STATE) {
 *             // use valid state, store it, use iter some more
 *             ...
 * 
 *             // later restore iter to the saved state:
 *             uiter_setState(iter, state, &errorCode);
 * 
 *             ...
 *         }
 * 
 *         ...
 *     }
 *     unorm_closeIter(uni);
 * }
 * \endcode
 *
 * See also the ICU test suites.
 *
 * @internal
 */
struct UNormIterator;
typedef struct UNormIterator UNormIterator;

/**
 * Size of a stack buffer to hold a UNormIterator, see the stackMem parameter
 * of unorm_openIter().
 *
 * @internal
 */
#define UNORM_ITER_SIZE 1024

/**
 * Open a normalizing iterator. Must be closed later.
 * Use unorm_setIter().
 *
 * @param stackMem Pointer to preallocated (stack-allocated) buffer to hold
 *                 the UNormIterator if possible; can be NULL.
 * @param stackMemSize Number of bytes at stackMem; can be 0,
 *                     or should be >= UNORM_ITER_SIZE for a non-NULL stackMem.
 * @param pErrorCode ICU error code
 * @return an allocated and pre-initialized UNormIterator
 * @internal
 */
U_CAPI UNormIterator * U_EXPORT2
unorm_openIter(void *stackMem, int32_t stackMemSize, UErrorCode *pErrorCode);

/**
 * Close a normalizing iterator.
 *
 * @param uni UNormIterator from unorm_openIter()
 * @internal
 */
U_CAPI void U_EXPORT2
unorm_closeIter(UNormIterator *uni);

/**
 * Set a UCharIterator and a normalization mode for the normalizing iterator
 * to wrap. The normalizing iterator will read from the character iterator,
 * normalize the text, and in turn deliver it with its own wrapper UCharIterator
 * interface which it returns.
 *
 * The source iterator remains at its current position through the unorm_setIter()
 * call but will be used and moved as soon as the
 * the returned normalizing iterator is.
 *
 * The returned interface pointer is valid for as long as the normalizing iterator
 * is open and until another unorm_setIter() call is made on it.
 *
 * The normalizing iterator's UCharIterator interface has the following properties:
 * - getIndex() and move() will almost always return UITER_UNKNOWN_INDEX
 * - getState() will return UITER_NO_STATE for unknown states for positions
 *              that are not at normalization boundaries
 *
 * @param uni UNormIterator from unorm_openIter()
 * @param iter The source text UCharIterator to be wrapped. It is aliases into the normalizing iterator.
 *             Must support getState() and setState().
 * @param mode The normalization mode.
 * @param pErrorCode ICU error code
 * @return an alias to the normalizing iterator's UCharIterator interface
 * @internal
 */
U_CAPI UCharIterator * U_EXPORT2
unorm_setIter(UNormIterator *uni, UCharIterator *iter, UNormalizationMode mode, UErrorCode *pErrorCode);

#endif /* uconfig.h switches */

#endif