initial commit, 4.5 stable

thirdparty/icu4c/common/unicode/ubiditransform.h

@@ -0,0 +1,326 @@
+/*
+******************************************************************************
+*
+* © 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