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 438