icuSources/layoutex/layout/plruns.h

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