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 444
