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