EIC code displayed by LXR master/​include/​unicode/​ubiditransform.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-18 10:13:09

 /*
 ******************************************************************************
 *
 * © 2016 and later: Unicode, Inc. and others.
 * License & terms of use: http://www.unicode.org/copyright.html
 *
 ******************************************************************************
 *   file name:  ubiditransform.h
 *   encoding:   UTF-8
 *   tab size:   8 (not used)
 *   indentation:4
 *
 *   created on: 2016jul24
 *   created by: Lina Kemmel
 *
 */
 
 #ifndef UBIDITRANSFORM_H
 #define UBIDITRANSFORM_H
 
 #include "unicode/utypes.h"
 #include "unicode/ubidi.h"
 #include "unicode/uchar.h"
 
 #if U_SHOW_CPLUSPLUS_API
 #include "unicode/localpointer.h"
 #endif   // U_SHOW_CPLUSPLUS_API
 
 /**
  * \file
  * \brief C API: Bidi Transformations
  */
 
 /**
  * `UBiDiOrder` indicates the order of text.
  *
  * This bidi transformation engine supports all possible combinations (4 in
  * total) of input and output text order:
  *
  *   - <logical input, visual output>: unless the output direction is RTL, this
  *     corresponds to a normal operation of the Bidi algorithm as described in the
  *     Unicode Technical Report and implemented by `UBiDi` when the
  *     reordering mode is set to `UBIDI_REORDER_DEFAULT`. Visual RTL
  *     mode is not supported by `UBiDi` and is accomplished through
  *     reversing a visual LTR string,
  *
  *   - <visual input, logical output>: unless the input direction is RTL, this
  *     corresponds to an "inverse bidi algorithm" in `UBiDi` with the
  *     reordering mode set to `UBIDI_REORDER_INVERSE_LIKE_DIRECT`.
  *     Visual RTL mode is not not supported by `UBiDi` and is
  *     accomplished through reversing a visual LTR string,
  *
  *   - <logical input, logical output>: if the input and output base directions
  *     mismatch, this corresponds to the `UBiDi` implementation with the
  *     reordering mode set to `UBIDI_REORDER_RUNS_ONLY`; and if the
  *     input and output base directions are identical, the transformation engine
  *     will only handle character mirroring and Arabic shaping operations without
  *     reordering,
  *
  *   - <visual input, visual output>: this reordering mode is not supported by
  *     the `UBiDi` engine; it implies character mirroring, Arabic
  *     shaping, and - if the input/output base directions mismatch -  string
  *     reverse operations.
  * @see ubidi_setInverse
  * @see ubidi_setReorderingMode
  * @see UBIDI_REORDER_DEFAULT
  * @see UBIDI_REORDER_INVERSE_LIKE_DIRECT
  * @see UBIDI_REORDER_RUNS_ONLY
  * @stable ICU 58
  */
 typedef enum {
     /** 0: Constant indicating a logical order.
       * This is the default for input text.
       * @stable ICU 58
       */
     UBIDI_LOGICAL = 0,
     /** 1: Constant indicating a visual order.
       * This is a default for output text.
       * @stable ICU 58
       */
     UBIDI_VISUAL
 } UBiDiOrder;
 
 /**
  * <code>UBiDiMirroring</code> indicates whether or not characters with the
  * "mirrored" property in RTL runs should be replaced with their mirror-image
  * counterparts.
  * @see UBIDI_DO_MIRRORING
  * @see ubidi_setReorderingOptions
  * @see ubidi_writeReordered
  * @see ubidi_writeReverse
  * @stable ICU 58
  */
 typedef enum {
     /** 0: Constant indicating that character mirroring should not be
       * performed.
       * This is the default.
       * @stable ICU 58
       */
     UBIDI_MIRRORING_OFF = 0,
     /** 1: Constant indicating that character mirroring should be performed.
       * This corresponds to calling <code>ubidi_writeReordered</code> or
       * <code>ubidi_writeReverse</code> with the
       * <code>UBIDI_DO_MIRRORING</code> option bit set.
       * @stable ICU 58
       */
     UBIDI_MIRRORING_ON
 } UBiDiMirroring;
 
 /**
  * Forward declaration of the <code>UBiDiTransform</code> structure that stores
  * information used by the layout transformation engine.
  * @stable ICU 58
  */
 typedef struct UBiDiTransform UBiDiTransform;
 
 /**
  * Performs transformation of text from the bidi layout defined by the input
  * ordering scheme to the bidi layout defined by the output ordering scheme,
  * and applies character mirroring and Arabic shaping operations.<p>
  * In terms of <code>UBiDi</code>, such a transformation implies:
  * <ul>
  * <li>calling <code>ubidi_setReorderingMode</code> as needed (when the
  * reordering mode is other than normal),</li>
  * <li>calling <code>ubidi_setInverse</code> as needed (when text should be
  * transformed from a visual to a logical form),</li>
  * <li>resolving embedding levels of each character in the input text by
  * calling <code>ubidi_setPara</code>,</li>
  * <li>reordering the characters based on the computed embedding levels, also
  * performing character mirroring as needed, and streaming the result to the
  * output, by calling <code>ubidi_writeReordered</code>,</li>
  * <li>performing Arabic digit and letter shaping on the output text by calling
  * <code>u_shapeArabic</code>.</li>
  * </ul>
  * An "ordering scheme" encompasses the base direction and the order of text,
  * and these characteristics must be defined by the caller for both input and
  * output explicitly .<p>
  * There are 36 possible combinations of <input, output> ordering schemes,
  * which are partially supported by <code>UBiDi</code> already. Examples of the
  * currently supported combinations:
  * <ul>
  * <li><Logical LTR, Visual LTR>: this is equivalent to calling
  * <code>ubidi_setPara</code> with <code>paraLevel == UBIDI_LTR</code>,</li>
  * <li><Logical RTL, Visual LTR>: this is equivalent to calling
  * <code>ubidi_setPara</code> with <code>paraLevel == UBIDI_RTL</code>,</li>
  * <li><Logical Default ("Auto") LTR, Visual LTR>: this is equivalent to
  * calling <code>ubidi_setPara</code> with
  * <code>paraLevel == UBIDI_DEFAULT_LTR</code>,</li>
  * <li><Logical Default ("Auto") RTL, Visual LTR>: this is equivalent to
  * calling <code>ubidi_setPara</code> with
  * <code>paraLevel == UBIDI_DEFAULT_RTL</code>,</li>
  * <li><Visual LTR, Logical LTR>: this is equivalent to
  * calling <code>ubidi_setInverse(UBiDi*, true)</code> and then
  * <code>ubidi_setPara</code> with <code>paraLevel == UBIDI_LTR</code>,</li>
  * <li><Visual LTR, Logical RTL>: this is equivalent to
  * calling <code>ubidi_setInverse(UBiDi*, true)</code> and then
  * <code>ubidi_setPara</code> with <code>paraLevel == UBIDI_RTL</code>.</li>
  * </ul>
  * All combinations that involve the Visual RTL scheme are unsupported by
  * <code>UBiDi</code>, for instance:
  * <ul>
  * <li><Logical LTR, Visual RTL>,</li>
  * <li><Visual RTL, Logical RTL>.</li>
  * </ul>
  * <p>Example of usage of the transformation engine:<br>
  * <pre>
  * \code
  * UChar text1[] = {'a', 'b', 'c', 0x0625, '1', 0};
  * UChar text2[] = {'a', 'b', 'c', 0x0625, '1', 0};
  * UErrorCode errorCode = U_ZERO_ERROR;
  * // Run a transformation.
  * ubiditransform_transform(pBidiTransform,
  *          text1, -1, text2, -1,
  *          UBIDI_LTR, UBIDI_VISUAL,
  *          UBIDI_RTL, UBIDI_LOGICAL,
  *          UBIDI_MIRRORING_OFF,
  *          U_SHAPE_DIGITS_AN2EN | U_SHAPE_DIGIT_TYPE_AN_EXTENDED,
  *          &errorCode);
  * // Do something with text2.
  *  text2[4] = '2';
  * // Run a reverse transformation.
  * ubiditransform_transform(pBidiTransform,
  *          text2, -1, text1, -1,
  *          UBIDI_RTL, UBIDI_LOGICAL,
  *          UBIDI_LTR, UBIDI_VISUAL,
  *          UBIDI_MIRRORING_OFF,
  *          U_SHAPE_DIGITS_EN2AN | U_SHAPE_DIGIT_TYPE_AN_EXTENDED,
  *          &errorCode);
  *\endcode
  * </pre>
  * </p>
  *
  * @param pBiDiTransform A pointer to a <code>UBiDiTransform</code> object
  *        allocated with <code>ubiditransform_open()</code> or
  *        <code>NULL</code>.<p>
  *        This object serves for one-time setup to amortize initialization
  *        overheads. Use of this object is not thread-safe. All other threads
  *        should allocate a new <code>UBiDiTransform</code> object by calling
  *        <code>ubiditransform_open()</code> before using it. Alternatively,
  *        a caller can set this parameter to <code>NULL</code>, in which case
  *        the object will be allocated by the engine on the fly.</p>
  * @param src A pointer to the text that the Bidi layout transformations will
  *        be performed on.
  *        <p><strong>Note:</strong> the text must be (at least)
  *        <code>srcLength</code> long.</p>
  * @param srcLength The length of the text, in number of UChars. If
  *        <code>length == -1</code> then the text must be zero-terminated.
  * @param dest A pointer to where the processed text is to be copied.
  * @param destSize The size of the <code>dest</code> buffer, in number of
  *        UChars. If the <code>U_SHAPE_LETTERS_UNSHAPE</code> option is set,
  *        then the destination length could be as large as
  *        <code>srcLength * 2</code>. Otherwise, the destination length will
  *        not exceed <code>srcLength</code>. If the caller reserves the last
  *        position for zero-termination, it should be excluded from
  *        <code>destSize</code>.
  *        <p><code>destSize == -1</code> is allowed and makes sense when
  *        <code>dest</code> was holds some meaningful value, e.g. that of
  *        <code>src</code>. In this case <code>dest</code> must be
  *        zero-terminated.</p>
  * @param inParaLevel A base embedding level of the input as defined in
  *        <code>ubidi_setPara</code> documentation for the
  *        <code>paraLevel</code> parameter.
  * @param inOrder An order of the input, which can be one of the
  *        <code>UBiDiOrder</code> values.
  * @param outParaLevel A base embedding level of the output as defined in
  *        <code>ubidi_setPara</code> documentation for the
  *        <code>paraLevel</code> parameter.
  * @param outOrder An order of the output, which can be one of the
  *        <code>UBiDiOrder</code> values.
  * @param doMirroring Indicates whether or not to perform character mirroring,
  *        and can accept one of the <code>UBiDiMirroring</code> values.
  * @param shapingOptions Arabic digit and letter shaping options defined in the
  *        ushape.h documentation.
  *        <p><strong>Note:</strong> Direction indicator options are computed by
  *        the transformation engine based on the effective ordering schemes, so
  *        user-defined direction indicators will be ignored.</p>
  * @param pErrorCode A pointer to an error code value.
  *
  * @return The destination length, i.e. the number of UChars written to
  *         <code>dest</code>. If the transformation fails, the return value
  *         will be 0 (and the error code will be written to
  *         <code>pErrorCode</code>).
  *
  * @see UBiDiLevel
  * @see UBiDiOrder
  * @see UBiDiMirroring
  * @see ubidi_setPara
  * @see u_shapeArabic
  * @stable ICU 58
  */
 U_CAPI uint32_t U_EXPORT2
 ubiditransform_transform(UBiDiTransform *pBiDiTransform,
             const UChar *src, int32_t srcLength,
             UChar *dest, int32_t destSize,
             UBiDiLevel inParaLevel, UBiDiOrder inOrder,
             UBiDiLevel outParaLevel, UBiDiOrder outOrder,
             UBiDiMirroring doMirroring, uint32_t shapingOptions,
             UErrorCode *pErrorCode);
 
 /**
  * Allocates a <code>UBiDiTransform</code> object. This object can be reused,
  * e.g. with different ordering schemes, mirroring or shaping options.<p>
  * <strong>Note:</strong>The object can only be reused in the same thread.
  * All other threads should allocate a new <code>UBiDiTransform</code> object
  * before using it.<p>
  * Example of usage:<p>
  * <pre>
  * \code
  * UErrorCode errorCode = U_ZERO_ERROR;
  * // Open a new UBiDiTransform.
  * UBiDiTransform* transform = ubiditransform_open(&errorCode);
  * // Run a transformation.
  * ubiditransform_transform(transform,
  *          text1, -1, text2, -1,
  *          UBIDI_RTL, UBIDI_LOGICAL,
  *          UBIDI_LTR, UBIDI_VISUAL,
  *          UBIDI_MIRRORING_ON,
  *          U_SHAPE_DIGITS_EN2AN,
  *          &errorCode);
  * // Do something with the output text and invoke another transformation using
  * //   that text as input.
  * ubiditransform_transform(transform,
  *          text2, -1, text3, -1,
  *          UBIDI_LTR, UBIDI_VISUAL,
  *          UBIDI_RTL, UBIDI_VISUAL,
  *          UBIDI_MIRRORING_ON,
  *          0, &errorCode);
  *\endcode
  * </pre>
  * <p>
  * The <code>UBiDiTransform</code> object must be deallocated by calling
  * <code>ubiditransform_close()</code>.
  *
  * @return An empty <code>UBiDiTransform</code> object.
  * @stable ICU 58
  */
 U_CAPI UBiDiTransform* U_EXPORT2
 ubiditransform_open(UErrorCode *pErrorCode);
 
 /**
  * Deallocates the given <code>UBiDiTransform</code> object.
  * @stable ICU 58
  */
 U_CAPI void U_EXPORT2
 ubiditransform_close(UBiDiTransform *pBidiTransform);
 
 #if U_SHOW_CPLUSPLUS_API
 
 U_NAMESPACE_BEGIN
 
 /**
  * \class LocalUBiDiTransformPointer
  * "Smart pointer" class, closes a UBiDiTransform via ubiditransform_close().
  * For most methods see the LocalPointerBase base class.
  *
  * @see LocalPointerBase
  * @see LocalPointer
  * @stable ICU 58
  */
 U_DEFINE_LOCAL_OPEN_POINTER(LocalUBiDiTransformPointer, UBiDiTransform, ubiditransform_close);
 
 U_NAMESPACE_END
 
 #endif
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team