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