Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ubiditransform.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 /*
jpayne@69 2 ******************************************************************************
jpayne@69 3 *
jpayne@69 4 * © 2016 and later: Unicode, Inc. and others.
jpayne@69 5 * License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 6 *
jpayne@69 7 ******************************************************************************
jpayne@69 8 * file name: ubiditransform.h
jpayne@69 9 * encoding: UTF-8
jpayne@69 10 * tab size: 8 (not used)
jpayne@69 11 * indentation:4
jpayne@69 12 *
jpayne@69 13 * created on: 2016jul24
jpayne@69 14 * created by: Lina Kemmel
jpayne@69 15 *
jpayne@69 16 */
jpayne@69 17
jpayne@69 18 #ifndef UBIDITRANSFORM_H
jpayne@69 19 #define UBIDITRANSFORM_H
jpayne@69 20
jpayne@69 21 #include "unicode/utypes.h"
jpayne@69 22 #include "unicode/ubidi.h"
jpayne@69 23 #include "unicode/uchar.h"
jpayne@69 24 #include "unicode/localpointer.h"
jpayne@69 25
jpayne@69 26 /**
jpayne@69 27 * \file
jpayne@69 28 * \brief Bidi Transformations
jpayne@69 29 */
jpayne@69 30
jpayne@69 31 /**
jpayne@69 32 * `UBiDiOrder` indicates the order of text.
jpayne@69 33 *
jpayne@69 34 * This bidi transformation engine supports all possible combinations (4 in
jpayne@69 35 * total) of input and output text order:
jpayne@69 36 *
jpayne@69 37 * - <logical input, visual output>: unless the output direction is RTL, this
jpayne@69 38 * corresponds to a normal operation of the Bidi algorithm as described in the
jpayne@69 39 * Unicode Technical Report and implemented by `UBiDi` when the
jpayne@69 40 * reordering mode is set to `UBIDI_REORDER_DEFAULT`. Visual RTL
jpayne@69 41 * mode is not supported by `UBiDi` and is accomplished through
jpayne@69 42 * reversing a visual LTR string,
jpayne@69 43 *
jpayne@69 44 * - <visual input, logical output>: unless the input direction is RTL, this
jpayne@69 45 * corresponds to an "inverse bidi algorithm" in `UBiDi` with the
jpayne@69 46 * reordering mode set to `UBIDI_REORDER_INVERSE_LIKE_DIRECT`.
jpayne@69 47 * Visual RTL mode is not not supported by `UBiDi` and is
jpayne@69 48 * accomplished through reversing a visual LTR string,
jpayne@69 49 *
jpayne@69 50 * - <logical input, logical output>: if the input and output base directions
jpayne@69 51 * mismatch, this corresponds to the `UBiDi` implementation with the
jpayne@69 52 * reordering mode set to `UBIDI_REORDER_RUNS_ONLY`; and if the
jpayne@69 53 * input and output base directions are identical, the transformation engine
jpayne@69 54 * will only handle character mirroring and Arabic shaping operations without
jpayne@69 55 * reordering,
jpayne@69 56 *
jpayne@69 57 * - <visual input, visual output>: this reordering mode is not supported by
jpayne@69 58 * the `UBiDi` engine; it implies character mirroring, Arabic
jpayne@69 59 * shaping, and - if the input/output base directions mismatch - string
jpayne@69 60 * reverse operations.
jpayne@69 61 * @see ubidi_setInverse
jpayne@69 62 * @see ubidi_setReorderingMode
jpayne@69 63 * @see UBIDI_REORDER_DEFAULT
jpayne@69 64 * @see UBIDI_REORDER_INVERSE_LIKE_DIRECT
jpayne@69 65 * @see UBIDI_REORDER_RUNS_ONLY
jpayne@69 66 * @stable ICU 58
jpayne@69 67 */
jpayne@69 68 typedef enum {
jpayne@69 69 /** 0: Constant indicating a logical order.
jpayne@69 70 * This is the default for input text.
jpayne@69 71 * @stable ICU 58
jpayne@69 72 */
jpayne@69 73 UBIDI_LOGICAL = 0,
jpayne@69 74 /** 1: Constant indicating a visual order.
jpayne@69 75 * This is a default for output text.
jpayne@69 76 * @stable ICU 58
jpayne@69 77 */
jpayne@69 78 UBIDI_VISUAL
jpayne@69 79 } UBiDiOrder;
jpayne@69 80
jpayne@69 81 /**
jpayne@69 82 * <code>UBiDiMirroring</code> indicates whether or not characters with the
jpayne@69 83 * "mirrored" property in RTL runs should be replaced with their mirror-image
jpayne@69 84 * counterparts.
jpayne@69 85 * @see UBIDI_DO_MIRRORING
jpayne@69 86 * @see ubidi_setReorderingOptions
jpayne@69 87 * @see ubidi_writeReordered
jpayne@69 88 * @see ubidi_writeReverse
jpayne@69 89 * @stable ICU 58
jpayne@69 90 */
jpayne@69 91 typedef enum {
jpayne@69 92 /** 0: Constant indicating that character mirroring should not be
jpayne@69 93 * performed.
jpayne@69 94 * This is the default.
jpayne@69 95 * @stable ICU 58
jpayne@69 96 */
jpayne@69 97 UBIDI_MIRRORING_OFF = 0,
jpayne@69 98 /** 1: Constant indicating that character mirroring should be performed.
jpayne@69 99 * This corresponds to calling <code>ubidi_writeReordered</code> or
jpayne@69 100 * <code>ubidi_writeReverse</code> with the
jpayne@69 101 * <code>UBIDI_DO_MIRRORING</code> option bit set.
jpayne@69 102 * @stable ICU 58
jpayne@69 103 */
jpayne@69 104 UBIDI_MIRRORING_ON
jpayne@69 105 } UBiDiMirroring;
jpayne@69 106
jpayne@69 107 /**
jpayne@69 108 * Forward declaration of the <code>UBiDiTransform</code> structure that stores
jpayne@69 109 * information used by the layout transformation engine.
jpayne@69 110 * @stable ICU 58
jpayne@69 111 */
jpayne@69 112 typedef struct UBiDiTransform UBiDiTransform;
jpayne@69 113
jpayne@69 114 /**
jpayne@69 115 * Performs transformation of text from the bidi layout defined by the input
jpayne@69 116 * ordering scheme to the bidi layout defined by the output ordering scheme,
jpayne@69 117 * and applies character mirroring and Arabic shaping operations.<p>
jpayne@69 118 * In terms of <code>UBiDi</code>, such a transformation implies:
jpayne@69 119 * <ul>
jpayne@69 120 * <li>calling <code>ubidi_setReorderingMode</code> as needed (when the
jpayne@69 121 * reordering mode is other than normal),</li>
jpayne@69 122 * <li>calling <code>ubidi_setInverse</code> as needed (when text should be
jpayne@69 123 * transformed from a visual to a logical form),</li>
jpayne@69 124 * <li>resolving embedding levels of each character in the input text by
jpayne@69 125 * calling <code>ubidi_setPara</code>,</li>
jpayne@69 126 * <li>reordering the characters based on the computed embedding levels, also
jpayne@69 127 * performing character mirroring as needed, and streaming the result to the
jpayne@69 128 * output, by calling <code>ubidi_writeReordered</code>,</li>
jpayne@69 129 * <li>performing Arabic digit and letter shaping on the output text by calling
jpayne@69 130 * <code>u_shapeArabic</code>.</li>
jpayne@69 131 * </ul>
jpayne@69 132 * An "ordering scheme" encompasses the base direction and the order of text,
jpayne@69 133 * and these characteristics must be defined by the caller for both input and
jpayne@69 134 * output explicitly .<p>
jpayne@69 135 * There are 36 possible combinations of <input, output> ordering schemes,
jpayne@69 136 * which are partially supported by <code>UBiDi</code> already. Examples of the
jpayne@69 137 * currently supported combinations:
jpayne@69 138 * <ul>
jpayne@69 139 * <li><Logical LTR, Visual LTR>: this is equivalent to calling
jpayne@69 140 * <code>ubidi_setPara</code> with <code>paraLevel == UBIDI_LTR</code>,</li>
jpayne@69 141 * <li><Logical RTL, Visual LTR>: this is equivalent to calling
jpayne@69 142 * <code>ubidi_setPara</code> with <code>paraLevel == UBIDI_RTL</code>,</li>
jpayne@69 143 * <li><Logical Default ("Auto") LTR, Visual LTR>: this is equivalent to
jpayne@69 144 * calling <code>ubidi_setPara</code> with
jpayne@69 145 * <code>paraLevel == UBIDI_DEFAULT_LTR</code>,</li>
jpayne@69 146 * <li><Logical Default ("Auto") RTL, Visual LTR>: this is equivalent to
jpayne@69 147 * calling <code>ubidi_setPara</code> with
jpayne@69 148 * <code>paraLevel == UBIDI_DEFAULT_RTL</code>,</li>
jpayne@69 149 * <li><Visual LTR, Logical LTR>: this is equivalent to
jpayne@69 150 * calling <code>ubidi_setInverse(UBiDi*, TRUE)</code> and then
jpayne@69 151 * <code>ubidi_setPara</code> with <code>paraLevel == UBIDI_LTR</code>,</li>
jpayne@69 152 * <li><Visual LTR, Logical RTL>: this is equivalent to
jpayne@69 153 * calling <code>ubidi_setInverse(UBiDi*, TRUE)</code> and then
jpayne@69 154 * <code>ubidi_setPara</code> with <code>paraLevel == UBIDI_RTL</code>.</li>
jpayne@69 155 * </ul>
jpayne@69 156 * All combinations that involve the Visual RTL scheme are unsupported by
jpayne@69 157 * <code>UBiDi</code>, for instance:
jpayne@69 158 * <ul>
jpayne@69 159 * <li><Logical LTR, Visual RTL>,</li>
jpayne@69 160 * <li><Visual RTL, Logical RTL>.</li>
jpayne@69 161 * </ul>
jpayne@69 162 * <p>Example of usage of the transformation engine:<br>
jpayne@69 163 * <pre>
jpayne@69 164 * \code
jpayne@69 165 * UChar text1[] = {'a', 'b', 'c', 0x0625, '1', 0};
jpayne@69 166 * UChar text2[] = {'a', 'b', 'c', 0x0625, '1', 0};
jpayne@69 167 * UErrorCode errorCode = U_ZERO_ERROR;
jpayne@69 168 * // Run a transformation.
jpayne@69 169 * ubiditransform_transform(pBidiTransform,
jpayne@69 170 * text1, -1, text2, -1,
jpayne@69 171 * UBIDI_LTR, UBIDI_VISUAL,
jpayne@69 172 * UBIDI_RTL, UBIDI_LOGICAL,
jpayne@69 173 * UBIDI_MIRRORING_OFF,
jpayne@69 174 * U_SHAPE_DIGITS_AN2EN | U_SHAPE_DIGIT_TYPE_AN_EXTENDED,
jpayne@69 175 * &errorCode);
jpayne@69 176 * // Do something with text2.
jpayne@69 177 * text2[4] = '2';
jpayne@69 178 * // Run a reverse transformation.
jpayne@69 179 * ubiditransform_transform(pBidiTransform,
jpayne@69 180 * text2, -1, text1, -1,
jpayne@69 181 * UBIDI_RTL, UBIDI_LOGICAL,
jpayne@69 182 * UBIDI_LTR, UBIDI_VISUAL,
jpayne@69 183 * UBIDI_MIRRORING_OFF,
jpayne@69 184 * U_SHAPE_DIGITS_EN2AN | U_SHAPE_DIGIT_TYPE_AN_EXTENDED,
jpayne@69 185 * &errorCode);
jpayne@69 186 *\endcode
jpayne@69 187 * </pre>
jpayne@69 188 * </p>
jpayne@69 189 *
jpayne@69 190 * @param pBiDiTransform A pointer to a <code>UBiDiTransform</code> object
jpayne@69 191 * allocated with <code>ubiditransform_open()</code> or
jpayne@69 192 * <code>NULL</code>.<p>
jpayne@69 193 * This object serves for one-time setup to amortize initialization
jpayne@69 194 * overheads. Use of this object is not thread-safe. All other threads
jpayne@69 195 * should allocate a new <code>UBiDiTransform</code> object by calling
jpayne@69 196 * <code>ubiditransform_open()</code> before using it. Alternatively,
jpayne@69 197 * a caller can set this parameter to <code>NULL</code>, in which case
jpayne@69 198 * the object will be allocated by the engine on the fly.</p>
jpayne@69 199 * @param src A pointer to the text that the Bidi layout transformations will
jpayne@69 200 * be performed on.
jpayne@69 201 * <p><strong>Note:</strong> the text must be (at least)
jpayne@69 202 * <code>srcLength</code> long.</p>
jpayne@69 203 * @param srcLength The length of the text, in number of UChars. If
jpayne@69 204 * <code>length == -1</code> then the text must be zero-terminated.
jpayne@69 205 * @param dest A pointer to where the processed text is to be copied.
jpayne@69 206 * @param destSize The size of the <code>dest</code> buffer, in number of
jpayne@69 207 * UChars. If the <code>U_SHAPE_LETTERS_UNSHAPE</code> option is set,
jpayne@69 208 * then the destination length could be as large as
jpayne@69 209 * <code>srcLength * 2</code>. Otherwise, the destination length will
jpayne@69 210 * not exceed <code>srcLength</code>. If the caller reserves the last
jpayne@69 211 * position for zero-termination, it should be excluded from
jpayne@69 212 * <code>destSize</code>.
jpayne@69 213 * <p><code>destSize == -1</code> is allowed and makes sense when
jpayne@69 214 * <code>dest</code> was holds some meaningful value, e.g. that of
jpayne@69 215 * <code>src</code>. In this case <code>dest</code> must be
jpayne@69 216 * zero-terminated.</p>
jpayne@69 217 * @param inParaLevel A base embedding level of the input as defined in
jpayne@69 218 * <code>ubidi_setPara</code> documentation for the
jpayne@69 219 * <code>paraLevel</code> parameter.
jpayne@69 220 * @param inOrder An order of the input, which can be one of the
jpayne@69 221 * <code>UBiDiOrder</code> values.
jpayne@69 222 * @param outParaLevel A base embedding level of the output as defined in
jpayne@69 223 * <code>ubidi_setPara</code> documentation for the
jpayne@69 224 * <code>paraLevel</code> parameter.
jpayne@69 225 * @param outOrder An order of the output, which can be one of the
jpayne@69 226 * <code>UBiDiOrder</code> values.
jpayne@69 227 * @param doMirroring Indicates whether or not to perform character mirroring,
jpayne@69 228 * and can accept one of the <code>UBiDiMirroring</code> values.
jpayne@69 229 * @param shapingOptions Arabic digit and letter shaping options defined in the
jpayne@69 230 * ushape.h documentation.
jpayne@69 231 * <p><strong>Note:</strong> Direction indicator options are computed by
jpayne@69 232 * the transformation engine based on the effective ordering schemes, so
jpayne@69 233 * user-defined direction indicators will be ignored.</p>
jpayne@69 234 * @param pErrorCode A pointer to an error code value.
jpayne@69 235 *
jpayne@69 236 * @return The destination length, i.e. the number of UChars written to
jpayne@69 237 * <code>dest</code>. If the transformation fails, the return value
jpayne@69 238 * will be 0 (and the error code will be written to
jpayne@69 239 * <code>pErrorCode</code>).
jpayne@69 240 *
jpayne@69 241 * @see UBiDiLevel
jpayne@69 242 * @see UBiDiOrder
jpayne@69 243 * @see UBiDiMirroring
jpayne@69 244 * @see ubidi_setPara
jpayne@69 245 * @see u_shapeArabic
jpayne@69 246 * @stable ICU 58
jpayne@69 247 */
jpayne@69 248 U_STABLE uint32_t U_EXPORT2
jpayne@69 249 ubiditransform_transform(UBiDiTransform *pBiDiTransform,
jpayne@69 250 const UChar *src, int32_t srcLength,
jpayne@69 251 UChar *dest, int32_t destSize,
jpayne@69 252 UBiDiLevel inParaLevel, UBiDiOrder inOrder,
jpayne@69 253 UBiDiLevel outParaLevel, UBiDiOrder outOrder,
jpayne@69 254 UBiDiMirroring doMirroring, uint32_t shapingOptions,
jpayne@69 255 UErrorCode *pErrorCode);
jpayne@69 256
jpayne@69 257 /**
jpayne@69 258 * Allocates a <code>UBiDiTransform</code> object. This object can be reused,
jpayne@69 259 * e.g. with different ordering schemes, mirroring or shaping options.<p>
jpayne@69 260 * <strong>Note:</strong>The object can only be reused in the same thread.
jpayne@69 261 * All other threads should allocate a new <code>UBiDiTransform</code> object
jpayne@69 262 * before using it.<p>
jpayne@69 263 * Example of usage:<p>
jpayne@69 264 * <pre>
jpayne@69 265 * \code
jpayne@69 266 * UErrorCode errorCode = U_ZERO_ERROR;
jpayne@69 267 * // Open a new UBiDiTransform.
jpayne@69 268 * UBiDiTransform* transform = ubiditransform_open(&errorCode);
jpayne@69 269 * // Run a transformation.
jpayne@69 270 * ubiditransform_transform(transform,
jpayne@69 271 * text1, -1, text2, -1,
jpayne@69 272 * UBIDI_RTL, UBIDI_LOGICAL,
jpayne@69 273 * UBIDI_LTR, UBIDI_VISUAL,
jpayne@69 274 * UBIDI_MIRRORING_ON,
jpayne@69 275 * U_SHAPE_DIGITS_EN2AN,
jpayne@69 276 * &errorCode);
jpayne@69 277 * // Do something with the output text and invoke another transformation using
jpayne@69 278 * // that text as input.
jpayne@69 279 * ubiditransform_transform(transform,
jpayne@69 280 * text2, -1, text3, -1,
jpayne@69 281 * UBIDI_LTR, UBIDI_VISUAL,
jpayne@69 282 * UBIDI_RTL, UBIDI_VISUAL,
jpayne@69 283 * UBIDI_MIRRORING_ON,
jpayne@69 284 * 0, &errorCode);
jpayne@69 285 *\endcode
jpayne@69 286 * </pre>
jpayne@69 287 * <p>
jpayne@69 288 * The <code>UBiDiTransform</code> object must be deallocated by calling
jpayne@69 289 * <code>ubiditransform_close()</code>.
jpayne@69 290 *
jpayne@69 291 * @return An empty <code>UBiDiTransform</code> object.
jpayne@69 292 * @stable ICU 58
jpayne@69 293 */
jpayne@69 294 U_STABLE UBiDiTransform* U_EXPORT2
jpayne@69 295 ubiditransform_open(UErrorCode *pErrorCode);
jpayne@69 296
jpayne@69 297 /**
jpayne@69 298 * Deallocates the given <code>UBiDiTransform</code> object.
jpayne@69 299 * @stable ICU 58
jpayne@69 300 */
jpayne@69 301 U_STABLE void U_EXPORT2
jpayne@69 302 ubiditransform_close(UBiDiTransform *pBidiTransform);
jpayne@69 303
jpayne@69 304 #if U_SHOW_CPLUSPLUS_API
jpayne@69 305
jpayne@69 306 U_NAMESPACE_BEGIN
jpayne@69 307
jpayne@69 308 /**
jpayne@69 309 * \class LocalUBiDiTransformPointer
jpayne@69 310 * "Smart pointer" class, closes a UBiDiTransform via ubiditransform_close().
jpayne@69 311 * For most methods see the LocalPointerBase base class.
jpayne@69 312 *
jpayne@69 313 * @see LocalPointerBase
jpayne@69 314 * @see LocalPointer
jpayne@69 315 * @stable ICU 58
jpayne@69 316 */
jpayne@69 317 U_DEFINE_LOCAL_OPEN_POINTER(LocalUBiDiTransformPointer, UBiDiTransform, ubiditransform_close);
jpayne@69 318
jpayne@69 319 U_NAMESPACE_END
jpayne@69 320
jpayne@69 321 #endif
jpayne@69 322
jpayne@69 323 #endif