[apple/icu.git] / icuSources / common / unicode / ushape.h

/*
******************************************************************************
*
*   Copyright (C) 2000-2001, International Business Machines
*   Corporation and others.  All Rights Reserved.
*
******************************************************************************
*   file name:  ushape.h
*   encoding:   US-ASCII
*   tab size:   8 (not used)
*   indentation:4
*
*   created on: 2000jun29
*   created by: Markus W. Scherer
*/

#ifndef __USHAPE_H__
#define __USHAPE_H__

#include "unicode/utypes.h"

/**
 * \file
 * \brief C API:  Arabic shaping
 * 
 */

/**
 * Shape Arabic text on a character basis.
 *
 * <p>This function performs basic operations for "shaping" Arabic text. It is most
 * useful for use with legacy data formats and legacy display technology
 * (simple terminals). All operations are performed on Unicode characters.</p>
 *
 * <p>Text-based shaping means that some character code points in the text are
 * replaced by others depending on the context. It transforms one kind of text
 * into another. In comparison, modern displays for Arabic text select
 * appropriate, context-dependent font glyphs for each text element, which means
 * that they transform text into a glyph vector.</p>
 *
 * <p>Text transformations are necessary when modern display technology is not
 * available or when text needs to be transformed to or from legacy formats that
 * use "shaped" characters. Since the Arabic script is cursive, connecting
 * adjacent letters to each other, computers select images for each letter based
 * on the surrounding letters. This usually results in four images per Arabic
 * letter: initial, middle, final, and isolated forms. In Unicode, on the other
 * hand, letters are normally stored abstract, and a display system is expected
 * to select the necessary glyphs. (This makes searching and other text
 * processing easier because the same letter has only one code.) It is possible
 * to mimic this with text transformations because there are characters in
 * Unicode that are rendered as letters with a specific shape
 * (or cursive connectivity). They were included for interoperability with
 * legacy systems and codepages, and for unsophisticated display systems.</p>
 *
 * <p>A second kind of text transformations is supported for Arabic digits:
 * For compatibility with legacy codepages that only include European digits,
 * it is possible to replace one set of digits by another, changing the
 * character code points. These operations can be performed for either
 * Arabic-Indic Digits (U+0660...U+0669) or Eastern (Extended) Arabic-Indic
 * digits (U+06f0...U+06f9).</p>
 *
 * <p>Some replacements may result in more or fewer characters (code points).
 * By default, this means that the destination buffer may receive text with a
 * length different from the source length. Some legacy systems rely on the
 * length of the text to be constant. They expect extra spaces to be added
 * or consumed either next to the affected character or at the end of the
 * text.</p>
 *
 * <p>For details about the available operations, see the description of the
 * <code>U_SHAPE_...</code> options.</p>
 *
 * @param source The input text.
 *
 * @param sourceLength The number of UChars in <code>source</code>.
 *
 * @param dest The destination buffer that will receive the results of the
 *             requested operations. It may be <code>NULL</code> only if
 *             <code>destSize</code> is 0. The source and destination must not
 *             overlap.
 *
 * @param destSize The size (capacity) of the destination buffer in UChars.
 *                 If <code>destSize</code> is 0, then no output is produced,
 *                 but the necessary buffer size is returned ("preflighting").
 *
 * @param options This is a 32-bit set of flags that specify the operations
 *                that are performed on the input text. If no error occurs,
 *                then the result will always be written to the destination
 *                buffer.
 *
 * @param pErrorCode must be a valid pointer to an error code value,
 *        which must not indicate a failure before the function call.
 *
 * @return The number of UChars written to the destination buffer.
 *         If an error occured, then no output was written, or it may be
 *         incomplete. If <code>U_BUFFER_OVERFLOW_ERROR</code> is set, then
 *         the return value indicates the necessary destination buffer size.
 * @stable ICU 2.0
 */
U_CAPI int32_t U_EXPORT2
u_shapeArabic(const UChar *source, int32_t sourceLength,
              UChar *dest, int32_t destSize,
              uint32_t options,
              UErrorCode *pErrorCode);

/**
 * Memory option: allow the result to have a different length than the source.
 * @stable ICU 2.0
 */
#define U_SHAPE_LENGTH_GROW_SHRINK              0

/**
 * Memory option: the result must have the same length as the source.
 * If more room is necessary, then try to consume spaces next to modified characters.
 * @stable ICU 2.0
 */
#define U_SHAPE_LENGTH_FIXED_SPACES_NEAR        1

/**
 * Memory option: the result must have the same length as the source.
 * If more room is necessary, then try to consume spaces at the end of the text.
 * @stable ICU 2.0
 */
#define U_SHAPE_LENGTH_FIXED_SPACES_AT_END      2

/**
 * Memory option: the result must have the same length as the source.
 * If more room is necessary, then try to consume spaces at the beginning of the text.
 * @stable ICU 2.0
 */
#define U_SHAPE_LENGTH_FIXED_SPACES_AT_BEGINNING 3

/** Bit mask for memory options. @stable ICU 2.0 */
#define U_SHAPE_LENGTH_MASK                     3


/** Direction indicator: the source is in logical (keyboard) order. @stable ICU 2.0 */
#define U_SHAPE_TEXT_DIRECTION_LOGICAL          0

/**
 * Direction indicator:
 * the source is in visual LTR order,
 * the leftmost displayed character stored first.
 * @stable ICU 2.0
 */
#define U_SHAPE_TEXT_DIRECTION_VISUAL_LTR       4

/** Bit mask for direction indicators. @stable ICU 2.0 */
#define U_SHAPE_TEXT_DIRECTION_MASK             4


/** Letter shaping option: do not perform letter shaping. @stable ICU 2.0 */
#define U_SHAPE_LETTERS_NOOP                    0

/** Letter shaping option: replace abstract letter characters by "shaped" ones. @stable ICU 2.0 */
#define U_SHAPE_LETTERS_SHAPE                   8

/** Letter shaping option: replace "shaped" letter characters by abstract ones. @stable ICU 2.0 */
#define U_SHAPE_LETTERS_UNSHAPE                 0x10

/**
 * Letter shaping option: replace abstract letter characters by "shaped" ones.
 * The only difference with U_SHAPE_LETTERS_SHAPE is that Tashkeel letters
 * are always "shaped" into the isolated form instead of the medial form
 * (selecting code points from the Arabic Presentation Forms-B block).
 * @stable ICU 2.0
 */
#define U_SHAPE_LETTERS_SHAPE_TASHKEEL_ISOLATED 0x18

/** Bit mask for letter shaping options. @stable ICU 2.0 */
#define U_SHAPE_LETTERS_MASK                    0x18


/** Digit shaping option: do not perform digit shaping. @stable ICU 2.0 */
#define U_SHAPE_DIGITS_NOOP                     0

/**
 * Digit shaping option:
 * Replace European digits (U+0030...) by Arabic-Indic digits.
 * @stable ICU 2.0
 */
#define U_SHAPE_DIGITS_EN2AN                    0x20

/**
 * Digit shaping option:
 * Replace Arabic-Indic digits by European digits (U+0030...).
 * @stable ICU 2.0
 */
#define U_SHAPE_DIGITS_AN2EN                    0x40

/**
 * Digit shaping option:
 * Replace European digits (U+0030...) by Arabic-Indic digits if the most recent
 * strongly directional character is an Arabic letter
 * (<code>u_charDirection()</code> result <code>U_RIGHT_TO_LEFT_ARABIC</code> [AL]).<br>
 * The direction of "preceding" depends on the direction indicator option.
 * For the first characters, the preceding strongly directional character
 * (initial state) is assumed to be not an Arabic letter
 * (it is <code>U_LEFT_TO_RIGHT</code> [L] or <code>U_RIGHT_TO_LEFT</code> [R]).
 * @stable ICU 2.0
 */
#define U_SHAPE_DIGITS_ALEN2AN_INIT_LR          0x60

/**
 * Digit shaping option:
 * Replace European digits (U+0030...) by Arabic-Indic digits if the most recent
 * strongly directional character is an Arabic letter
 * (<code>u_charDirection()</code> result <code>U_RIGHT_TO_LEFT_ARABIC</code> [AL]).<br>
 * The direction of "preceding" depends on the direction indicator option.
 * For the first characters, the preceding strongly directional character
 * (initial state) is assumed to be an Arabic letter.
 * @stable ICU 2.0
 */
#define U_SHAPE_DIGITS_ALEN2AN_INIT_AL          0x80

/** Not a valid option value. May be replaced by a new option. @stable ICU 2.0 */
#define U_SHAPE_DIGITS_RESERVED                 0xa0

/** Bit mask for digit shaping options. @stable ICU 2.0 */
#define U_SHAPE_DIGITS_MASK                     0xe0


/** Digit type option: Use Arabic-Indic digits (U+0660...U+0669). @stable ICU 2.0 */
#define U_SHAPE_DIGIT_TYPE_AN                   0

/** Digit type option: Use Eastern (Extended) Arabic-Indic digits (U+06f0...U+06f9). @stable ICU 2.0 */
#define U_SHAPE_DIGIT_TYPE_AN_EXTENDED          0x100

/** Not a valid option value. May be replaced by a new option. @stable ICU 2.0 */
#define U_SHAPE_DIGIT_TYPE_RESERVED             0x200

/** Bit mask for digit type options. @stable ICU 2.0 */
#define U_SHAPE_DIGIT_TYPE_MASK                 0x3f00

#endif
Commit	Line	Data
b75a7d8f A	1	/*
	2	******************************************************************************
	3	*
	4	* Copyright (C) 2000-2001, International Business Machines
	5	* Corporation and others. All Rights Reserved.
	6	*
	7	******************************************************************************
	8	* file name: ushape.h
	9	* encoding: US-ASCII
	10	* tab size: 8 (not used)
	11	* indentation:4
	12	*
	13	* created on: 2000jun29
	14	* created by: Markus W. Scherer
	15	*/
	16
	17	#ifndef __USHAPE_H__
	18	#define __USHAPE_H__
	19
	20	#include "unicode/utypes.h"
	21
	22	/**
	23	* \file
	24	* \brief C API: Arabic shaping
	25	*
	26	*/
	27
	28	/**
	29	* Shape Arabic text on a character basis.
	30	*
	31	* <p>This function performs basic operations for "shaping" Arabic text. It is most
	32	* useful for use with legacy data formats and legacy display technology
	33	* (simple terminals). All operations are performed on Unicode characters.</p>
	34	*
	35	* <p>Text-based shaping means that some character code points in the text are
	36	* replaced by others depending on the context. It transforms one kind of text
	37	* into another. In comparison, modern displays for Arabic text select
	38	* appropriate, context-dependent font glyphs for each text element, which means
	39	* that they transform text into a glyph vector.</p>
	40	*
	41	* <p>Text transformations are necessary when modern display technology is not
	42	* available or when text needs to be transformed to or from legacy formats that
	43	* use "shaped" characters. Since the Arabic script is cursive, connecting
	44	* adjacent letters to each other, computers select images for each letter based
	45	* on the surrounding letters. This usually results in four images per Arabic
	46	* letter: initial, middle, final, and isolated forms. In Unicode, on the other
	47	* hand, letters are normally stored abstract, and a display system is expected
	48	* to select the necessary glyphs. (This makes searching and other text
	49	* processing easier because the same letter has only one code.) It is possible
	50	* to mimic this with text transformations because there are characters in
	51	* Unicode that are rendered as letters with a specific shape
	52	* (or cursive connectivity). They were included for interoperability with
	53	* legacy systems and codepages, and for unsophisticated display systems.</p>
	54	*
	55	* <p>A second kind of text transformations is supported for Arabic digits:
	56	* For compatibility with legacy codepages that only include European digits,
	57	* it is possible to replace one set of digits by another, changing the
	58	* character code points. These operations can be performed for either
	59	* Arabic-Indic Digits (U+0660...U+0669) or Eastern (Extended) Arabic-Indic
	60	* digits (U+06f0...U+06f9).</p>
	61	*
	62	* <p>Some replacements may result in more or fewer characters (code points).
	63	* By default, this means that the destination buffer may receive text with a
	64	* length different from the source length. Some legacy systems rely on the
65	* length of the text to be constant. They expect extra spaces to be added
66	* or consumed either next to the affected character or at the end of the
67	* text.</p>
68	*
69	* <p>For details about the available operations, see the description of the
70	* <code>U_SHAPE_...</code> options.</p>
71	*
72	* @param source The input text.
73	*
74	* @param sourceLength The number of UChars in <code>source</code>.
75	*
76	* @param dest The destination buffer that will receive the results of the
77	* requested operations. It may be <code>NULL</code> only if
78	* <code>destSize</code> is 0. The source and destination must not
79	* overlap.
80	*
81	* @param destSize The size (capacity) of the destination buffer in UChars.
82	* If <code>destSize</code> is 0, then no output is produced,
83	* but the necessary buffer size is returned ("preflighting").
84	*
85	* @param options This is a 32-bit set of flags that specify the operations
86	* that are performed on the input text. If no error occurs,
87	* then the result will always be written to the destination
88	* buffer.
89	*
90	* @param pErrorCode must be a valid pointer to an error code value,
91	* which must not indicate a failure before the function call.
92	*
93	* @return The number of UChars written to the destination buffer.
94	* If an error occured, then no output was written, or it may be
95	* incomplete. If <code>U_BUFFER_OVERFLOW_ERROR</code> is set, then
96	* the return value indicates the necessary destination buffer size.
97	* @stable ICU 2.0
98	*/
99	U_CAPI int32_t U_EXPORT2
100	u_shapeArabic(const UChar *source, int32_t sourceLength,
101	UChar *dest, int32_t destSize,
102	uint32_t options,
103	UErrorCode *pErrorCode);
104
105	/**
106	* Memory option: allow the result to have a different length than the source.
107	* @stable ICU 2.0
108	*/
109	#define U_SHAPE_LENGTH_GROW_SHRINK 0
110
111	/**
112	* Memory option: the result must have the same length as the source.
113	* If more room is necessary, then try to consume spaces next to modified characters.
114	* @stable ICU 2.0
115	*/
116	#define U_SHAPE_LENGTH_FIXED_SPACES_NEAR 1
117
118	/**
119	* Memory option: the result must have the same length as the source.
120	* If more room is necessary, then try to consume spaces at the end of the text.
121	* @stable ICU 2.0
122	*/
123	#define U_SHAPE_LENGTH_FIXED_SPACES_AT_END 2
124
125	/**
126	* Memory option: the result must have the same length as the source.
127	* If more room is necessary, then try to consume spaces at the beginning of the text.
128	* @stable ICU 2.0
129	*/
130	#define U_SHAPE_LENGTH_FIXED_SPACES_AT_BEGINNING 3
131
132	/** Bit mask for memory options. @stable ICU 2.0 */
133	#define U_SHAPE_LENGTH_MASK 3
134
135
136	/** Direction indicator: the source is in logical (keyboard) order. @stable ICU 2.0 */
137	#define U_SHAPE_TEXT_DIRECTION_LOGICAL 0
138
139	/**
140	* Direction indicator:
141	* the source is in visual LTR order,
142	* the leftmost displayed character stored first.
143	* @stable ICU 2.0
144	*/
145	#define U_SHAPE_TEXT_DIRECTION_VISUAL_LTR 4
146
147	/** Bit mask for direction indicators. @stable ICU 2.0 */
148	#define U_SHAPE_TEXT_DIRECTION_MASK 4
149
150
151	/** Letter shaping option: do not perform letter shaping. @stable ICU 2.0 */
152	#define U_SHAPE_LETTERS_NOOP 0
153
154	/** Letter shaping option: replace abstract letter characters by "shaped" ones. @stable ICU 2.0 */
155	#define U_SHAPE_LETTERS_SHAPE 8
156
157	/** Letter shaping option: replace "shaped" letter characters by abstract ones. @stable ICU 2.0 */
158	#define U_SHAPE_LETTERS_UNSHAPE 0x10
159
160	/**
161	* Letter shaping option: replace abstract letter characters by "shaped" ones.
162	* The only difference with U_SHAPE_LETTERS_SHAPE is that Tashkeel letters
163	* are always "shaped" into the isolated form instead of the medial form
164	* (selecting code points from the Arabic Presentation Forms-B block).
165	* @stable ICU 2.0
166	*/
167	#define U_SHAPE_LETTERS_SHAPE_TASHKEEL_ISOLATED 0x18
168
169	/** Bit mask for letter shaping options. @stable ICU 2.0 */
170	#define U_SHAPE_LETTERS_MASK 0x18
171
172
173	/** Digit shaping option: do not perform digit shaping. @stable ICU 2.0 */
174	#define U_SHAPE_DIGITS_NOOP 0
175
176	/**
177	* Digit shaping option:
178	* Replace European digits (U+0030...) by Arabic-Indic digits.
179	* @stable ICU 2.0
180	*/
181	#define U_SHAPE_DIGITS_EN2AN 0x20
182
183	/**
184	* Digit shaping option:
185	* Replace Arabic-Indic digits by European digits (U+0030...).
186	* @stable ICU 2.0
187	*/
188	#define U_SHAPE_DIGITS_AN2EN 0x40
189
190	/**
191	* Digit shaping option:
192	* Replace European digits (U+0030...) by Arabic-Indic digits if the most recent
193	* strongly directional character is an Arabic letter
194	* (<code>u_charDirection()</code> result <code>U_RIGHT_TO_LEFT_ARABIC</code> [AL]).<br>
195	* The direction of "preceding" depends on the direction indicator option.
196	* For the first characters, the preceding strongly directional character
197	* (initial state) is assumed to be not an Arabic letter
198	* (it is <code>U_LEFT_TO_RIGHT</code> [L] or <code>U_RIGHT_TO_LEFT</code> [R]).
199	* @stable ICU 2.0
200	*/
201	#define U_SHAPE_DIGITS_ALEN2AN_INIT_LR 0x60
202
203	/**
204	* Digit shaping option:
205	* Replace European digits (U+0030...) by Arabic-Indic digits if the most recent
206	* strongly directional character is an Arabic letter
207	* (<code>u_charDirection()</code> result <code>U_RIGHT_TO_LEFT_ARABIC</code> [AL]).<br>
208	* The direction of "preceding" depends on the direction indicator option.
209	* For the first characters, the preceding strongly directional character
210	* (initial state) is assumed to be an Arabic letter.
211	* @stable ICU 2.0
212	*/
213	#define U_SHAPE_DIGITS_ALEN2AN_INIT_AL 0x80
214
215	/** Not a valid option value. May be replaced by a new option. @stable ICU 2.0 */
216	#define U_SHAPE_DIGITS_RESERVED 0xa0
217
218	/** Bit mask for digit shaping options. @stable ICU 2.0 */
219	#define U_SHAPE_DIGITS_MASK 0xe0
220
221
222	/** Digit type option: Use Arabic-Indic digits (U+0660...U+0669). @stable ICU 2.0 */
223	#define U_SHAPE_DIGIT_TYPE_AN 0
224
225	/** Digit type option: Use Eastern (Extended) Arabic-Indic digits (U+06f0...U+06f9). @stable ICU 2.0 */
226	#define U_SHAPE_DIGIT_TYPE_AN_EXTENDED 0x100
227
228	/** Not a valid option value. May be replaced by a new option. @stable ICU 2.0 */
229	#define U_SHAPE_DIGIT_TYPE_RESERVED 0x200
230
231	/** Bit mask for digit type options. @stable ICU 2.0 */
232	#define U_SHAPE_DIGIT_TYPE_MASK 0x3f00
233
234	#endif