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