icuSources/layoutex/layout/plruns.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4  *
   5  * (C) Copyright IBM Corp. 1998-2011 - All Rights Reserved
   6  *
   7  */
   8
   9 #ifndef __PLRUNS_H
  10 #define __PLRUNS_H
  11
  12 #include "unicode/utypes.h"
  13
  14 #ifndef U_HIDE_INTERNAL_API
  15
  16 #include "unicode/ubidi.h"
  17 #include "layout/LETypes.h"
  18
  19 #include "layout/loengine.h"
  20
  21 /**
  22  * Opaque datatype representing an array of font runs
  23  * @internal
  24  */
  25 typedef void pl_fontRuns;
  26 /**
  27  * Opaque datatype representing an array of value runs
  28  * @internal
  29  */
  30 typedef void pl_valueRuns;
  31 /**
  32  * Opaque datatype representing an array of locale runs
  33  * @internal
  34  */
  35 typedef void pl_localeRuns;
  36
  37 /**
  38  * \file
  39  * \brief C API for run arrays.
  40  *
  41  * This is a technology preview. The API may
  42  * change significantly.
  43  *
  44  */
  45
  46 /**
  47  * Construct a <code>pl_fontRuns</code> object from pre-existing arrays of fonts
  48  * and limit indices.
  49  *
  50  * @param fonts is the address of an array of pointers to <code>le_font</code> objects. This
  51  *              array, and the <code>le_font</code> objects to which it points must remain
  52  *              valid until the <code>pl_fontRuns</code> object is closed.
  53  *
  54  * @param limits is the address of an array of limit indices. This array must remain valid until
  55  *               the <code>pl_fontRuns</code> object is closed.
  56  *
  57  * @param count is the number of entries in the two arrays.
  58  *
  59  * @internal
  60  */
  61 U_INTERNAL pl_fontRuns * U_EXPORT2
  62 pl_openFontRuns(const le_font **fonts,
  63                 const le_int32 *limits,
  64                 le_int32 count);
  65
  66 /**
  67  * Construct an empty <code>pl_fontRuns</code> object. Clients can add font and limit
  68  * indices arrays using the <code>pl_addFontRun</code> routine.
  69  *
  70  * @param initialCapacity is the initial size of the font and limit indices arrays. If
  71  *                        this value is zero, no arrays will be allocated.
  72  *
  73  * @see pl_addFontRun
  74  *
  75  * @internal
  76  */
  77 U_INTERNAL pl_fontRuns * U_EXPORT2
  78 pl_openEmptyFontRuns(le_int32 initialCapacity);
  79
  80 /**
  81  * Close the given <code>pl_fontRuns</code> object. Once this
  82  * call returns, the object can no longer be referenced.
  83  *
  84  * @param fontRuns is the <code>pl_fontRuns</code> object.
  85  *
  86  * @internal
  87  */
  88 U_INTERNAL void U_EXPORT2
  89 pl_closeFontRuns(pl_fontRuns *fontRuns);
  90
  91 /**
  92  * Get the number of font runs.
  93  *
  94  * @param fontRuns is the <code>pl_fontRuns</code> object.
  95  *
  96  * @return the number of entries in the limit indices array.
  97  *
  98  * @internal
  99  */
 100 U_INTERNAL le_int32 U_EXPORT2
 101 pl_getFontRunCount(const pl_fontRuns *fontRuns);
 102
 103 /**
 104  * Reset the number of font runs to zero.
 105  *
 106  * @param fontRuns is the <code>pl_fontRuns</code> object.
 107  *
 108  * @internal
 109  */
 110 U_INTERNAL void U_EXPORT2
 111 pl_resetFontRuns(pl_fontRuns *fontRuns);
 112
 113 /**
 114  * Get the limit index for the last font run. This is the
 115  * number of characters in the text.
 116  *
 117  * @param fontRuns is the <code>pl_fontRuns</code> object.
 118  *
 119  * @return the last limit index.
 120  *
 121  * @internal
 122  */
 123 U_INTERNAL le_int32 U_EXPORT2
 124 pl_getFontRunLastLimit(const pl_fontRuns *fontRuns);
 125
 126 /**
 127  * Get the limit index for a particular font run.
 128  *
 129  * @param fontRuns is the <code>pl_fontRuns</code> object.
 130  * @param run is the run. This is an index into the limit index array.
 131  *
 132  * @return the limit index for the run, or -1 if <code>run</code> is out of bounds.
 133  *
 134  * @internal
 135  */
 136 U_INTERNAL le_int32 U_EXPORT2
 137 pl_getFontRunLimit(const pl_fontRuns *fontRuns,
 138                    le_int32 run);
 139
 140 /**
 141  * Get the <code>le_font</code> object assoicated with the given run
 142  * of text. Use <code>pl_getFontRunLimit(run)</code> to get the corresponding
 143  * limit index.
 144  *
 145  * @param fontRuns is the <code>pl_fontRuns</code> object.
 146  * @param run is the index into the font and limit indices arrays.
 147  *
 148  * @return the <code>le_font</code> associated with the given text run.
 149  *
 150  * @internal
 151  */
 152 U_INTERNAL const le_font * U_EXPORT2
 153 pl_getFontRunFont(const pl_fontRuns *fontRuns,
 154                   le_int32 run);
 155
 156
 157 /**
 158  * Add a new font run to the given <code>pl_fontRuns</code> object.
 159  *
 160  * If the <code>pl_fontRuns</code> object was not created by calling
 161  * <code>pl_openEmptyFontRuns</code>, this method will return a run index of -1.
 162  *
 163  * @param fontRuns is the <code>pl_fontRuns</code> object.
 164  *
 165  * @param font is the address of the <code>le_font</code> to add. This object must
 166  *             remain valid until the <code>pl_fontRuns</code> object is closed.
 167  *
 168  * @param limit is the limit index to add
 169  *
 170  * @return the run index where the font and limit index were stored, or -1 if
 171  *         the run cannot be added.
 172  *
 173  * @internal
 174  */
 175 U_INTERNAL le_int32 U_EXPORT2
 176 pl_addFontRun(pl_fontRuns *fontRuns,
 177               const le_font *font,
 178               le_int32 limit);
 179
 180 /**
 181  * Construct a <code>pl_valueRuns</code> object from pre-existing arrays of values
 182  * and limit indices.
 183  *
 184  * @param values is the address of an array of values. This array must remain valid until
 185                  the <code>pl_valueRuns</code> object is closed.
 186  *
 187  * @param limits is the address of an array of limit indices. This array must remain valid until
 188  *               the <code>pl_valueRuns</code> object is closed.
 189  *
 190  * @param count is the number of entries in the two arrays.
 191  *
 192  * @internal
 193  */
 194 U_INTERNAL pl_valueRuns * U_EXPORT2
 195 pl_openValueRuns(const le_int32 *values,
 196                  const le_int32 *limits,
 197                  le_int32 count);
 198
 199 /**
 200  * Construct an empty <code>pl_valueRuns</code> object. Clients can add values and limits
 201  * using the <code>pl_addValueRun</code> routine.
 202  *
 203  * @param initialCapacity is the initial size of the value and limit indices arrays. If
 204  *                        this value is zero, no arrays will be allocated.
 205  *
 206  * @see pl_addValueRun
 207  *
 208  * @internal
 209  */
 210 U_INTERNAL pl_valueRuns * U_EXPORT2
 211 pl_openEmptyValueRuns(le_int32 initialCapacity);
 212
 213 /**
 214  * Close the given <code>pl_valueRuns</code> object. Once this
 215  * call returns, the object can no longer be referenced.
 216  *
 217  * @param valueRuns is the <code>pl_valueRuns</code> object.
 218  *
 219  * @internal
 220  */
 221 U_INTERNAL void U_EXPORT2
 222 pl_closeValueRuns(pl_valueRuns *valueRuns);
 223
 224 /**
 225  * Get the number of value runs.
 226  *
 227  * @param valueRuns is the <code>pl_valueRuns</code> object.
 228  *
 229  * @return the number of value runs.
 230  *
 231  * @internal
 232  */
 233 U_INTERNAL le_int32 U_EXPORT2
 234 pl_getValueRunCount(const pl_valueRuns *valueRuns);
 235
 236 /**
 237  * Reset the number of value runs to zero.
 238  *
 239  * @param valueRuns is the <code>pl_valueRuns</code> object.
 240  *
 241  * @internal
 242  */
 243 U_INTERNAL void U_EXPORT2
 244 pl_resetValueRuns(pl_valueRuns *valueRuns);
 245
 246 /**
 247  * Get the limit index for the last value run. This is the
 248  * number of characters in the text.
 249  *
 250  * @param valueRuns is the <code>pl_valueRuns</code> object.
 251  *
 252  * @return the last limit index.
 253  *
 254  * @internal
 255  */
 256 U_INTERNAL le_int32 U_EXPORT2
 257 pl_getValueRunLastLimit(const pl_valueRuns *valueRuns);
 258
 259 /**
 260  * Get the limit index for a particular value run.
 261  *
 262  * @param valueRuns is the <code>pl_valueRuns</code> object.
 263  * @param run is the run index.
 264  *
 265  * @return the limit index for the run, or -1 if <code>run</code> is out of bounds.
 266  *
 267  * @internal
 268  */
 269 U_INTERNAL le_int32 U_EXPORT2
 270 pl_getValueRunLimit(const pl_valueRuns *valueRuns,
 271                      le_int32 run);
 272
 273 /**
 274  * Get the value assoicated with the given run * of text. Use
 275  * <code>pl_getValueRunLimit(run)</code> to get the corresponding
 276  * limit index.
 277  *
 278  * @param valueRuns is the <code>pl_valueRuns</code> object.
 279  * @param run is the run index.
 280  *
 281  * @return the value associated with the given text run.
 282  *
 283  * @internal
 284  */
 285 U_INTERNAL le_int32 U_EXPORT2
 286 pl_getValueRunValue(const pl_valueRuns *valueRuns,
 287                     le_int32 run);
 288
 289
 290 /**
 291  * Add a new font run to the given <code>pl_valueRuns</code> object.
 292  *
 293  * If the <code>pl_valueRuns</code> object was not created by calling
 294  * <code>pl_openEmptyFontRuns</code>, this method will return a run index of -1.
 295  *
 296  * @param valueRuns is the <code>pl_valueRuns</code> object.
 297  *
 298  * @param value is the value to add.
 299  *
 300  * @param limit is the limit index to add
 301  *
 302  * @return the run index where the font and limit index were stored, or -1 if
 303  *         the run cannot be added.
 304  *
 305  * @internal
 306  */
 307 U_INTERNAL le_int32 U_EXPORT2
 308 pl_addValueRun(pl_valueRuns *valueRuns,
 309                le_int32 value,
 310                le_int32 limit);
 311
 312 /**
 313  * Construct a <code>pl_localeRuns</code> object from pre-existing arrays of fonts
 314  * and limit indices.
 315  *
 316  * @param locales is the address of an array of pointers to locale name strings. This
 317  *                array must remain valid until the <code>pl_localeRuns</code> object is destroyed.
 318  *
 319  * @param limits is the address of an array of limit indices. This array must remain valid until
 320  *               the <code>pl_valueRuns</code> object is destroyed.
 321  *
 322  * @param count is the number of entries in the two arrays.
 323  *
 324  * @internal
 325  */
 326 U_INTERNAL pl_localeRuns * U_EXPORT2
 327 pl_openLocaleRuns(const char **locales,
 328                   const le_int32 *limits,
 329                   le_int32 count);
 330
 331 /**
 332  * Construct an empty <code>pl_localeRuns</code> object. Clients can add font and limit
 333  * indices arrays using the <code>pl_addFontRun</code> routine.
 334  *
 335  * @param initialCapacity is the initial size of the font and limit indices arrays. If
 336  *                        this value is zero, no arrays will be allocated.
 337  *
 338  * @see pl_addLocaleRun
 339  *
 340  * @internal
 341  */
 342 U_INTERNAL pl_localeRuns * U_EXPORT2
 343 pl_openEmptyLocaleRuns(le_int32 initialCapacity);
 344
 345 /**
 346  * Close the given <code>pl_localeRuns</code> object. Once this
 347  * call returns, the object can no longer be referenced.
 348  *
 349  * @param localeRuns is the <code>pl_localeRuns</code> object.
 350  *
 351  * @internal
 352  */
 353 U_INTERNAL void U_EXPORT2
 354 pl_closeLocaleRuns(pl_localeRuns *localeRuns);
 355
 356 /**
 357  * Get the number of font runs.
 358  *
 359  * @param localeRuns is the <code>pl_localeRuns</code> object.
 360  *
 361  * @return the number of entries in the limit indices array.
 362  *
 363  * @internal
 364  */
 365 U_INTERNAL le_int32 U_EXPORT2
 366 pl_getLocaleRunCount(const pl_localeRuns *localeRuns);
 367
 368 /**
 369  * Reset the number of locale runs to zero.
 370  *
 371  * @param localeRuns is the <code>pl_localeRuns</code> object.
 372  *
 373  * @internal
 374  */
 375 U_INTERNAL void U_EXPORT2
 376 pl_resetLocaleRuns(pl_localeRuns *localeRuns);
 377
 378 /**
 379  * Get the limit index for the last font run. This is the
 380  * number of characters in the text.
 381  *
 382  * @param localeRuns is the <code>pl_localeRuns</code> object.
 383  *
 384  * @return the last limit index.
 385  *
 386  * @internal
 387  */
 388 U_INTERNAL le_int32 U_EXPORT2
 389 pl_getLocaleRunLastLimit(const pl_localeRuns *localeRuns);
 390
 391 /**
 392  * Get the limit index for a particular font run.
 393  *
 394  * @param localeRuns is the <code>pl_localeRuns</code> object.
 395  * @param run is the run. This is an index into the limit index array.
 396  *
 397  * @return the limit index for the run, or -1 if <code>run</code> is out of bounds.
 398  *
 399  * @internal
 400  */
 401 U_INTERNAL le_int32 U_EXPORT2
 402 pl_getLocaleRunLimit(const pl_localeRuns *localeRuns,
 403                      le_int32 run);
 404
 405 /**
 406  * Get the <code>le_font</code> object assoicated with the given run
 407  * of text. Use <code>pl_getLocaleRunLimit(run)</code> to get the corresponding
 408  * limit index.
 409  *
 410  * @param localeRuns is the <code>pl_localeRuns</code> object.
 411  * @param run is the index into the font and limit indices arrays.
 412  *
 413  * @return the <code>le_font</code> associated with the given text run.
 414  *
 415  * @internal
 416  */
 417 U_INTERNAL const char * U_EXPORT2
 418 pl_getLocaleRunLocale(const pl_localeRuns *localeRuns,
 419                       le_int32 run);
 420
 421
 422 /**
 423  * Add a new run to the given <code>pl_localeRuns</code> object.
 424  *
 425  * If the <code>pl_localeRuns</code> object was not created by calling
 426  * <code>pl_openEmptyLocaleRuns</code>, this method will return a run index of -1.
 427  *
 428  * @param localeRuns is the <code>pl_localeRuns</code> object.
 429  *
 430  * @param locale is the name of the locale to add. This name must
 431  *               remain valid until the <code>pl_localeRuns</code> object is closed.
 432  *
 433  * @param limit is the limit index to add
 434  *
 435  * @return the run index where the font and limit index were stored, or -1 if
 436  *         the run cannot be added.
 437  *
 438  * @internal
 439  */
 440 U_INTERNAL le_int32 U_EXPORT2
 441 pl_addLocaleRun(pl_localeRuns *localeRuns,
 442                 const char *locale,
 443                 le_int32 limit);
 444
 445 #endif  /* U_HIDE_INTERNAL_API */
 446 #endif