1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
5 * (C) Copyright IBM Corp. 1998-2011 - All Rights Reserved
12 #include "unicode/utypes.h"
14 #ifndef U_HIDE_INTERNAL_API
16 #include "unicode/ubidi.h"
17 #include "layout/LETypes.h"
19 #include "layout/loengine.h"
22 * Opaque datatype representing an array of font runs
24 typedef void pl_fontRuns;
26 * Opaque datatype representing an array of value runs
28 typedef void pl_valueRuns;
30 * Opaque datatype representing an array of locale runs
32 typedef void pl_localeRuns;
36 * \brief C API for run arrays.
38 * This is a technology preview. The API may
39 * change significantly.
44 * Construct a <code>pl_fontRuns</code> object from pre-existing arrays of fonts
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.
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.
54 * @param count is the number of entries in the two arrays.
58 U_INTERNAL pl_fontRuns * U_EXPORT2
59 pl_openFontRuns(const le_font **fonts,
60 const le_int32 *limits,
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.
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.
74 U_INTERNAL pl_fontRuns * U_EXPORT2
75 pl_openEmptyFontRuns(le_int32 initialCapacity);
78 * Close the given <code>pl_fontRuns</code> object. Once this
79 * call returns, the object can no longer be referenced.
81 * @param fontRuns is the <code>pl_fontRuns</code> object.
85 U_INTERNAL void U_EXPORT2
86 pl_closeFontRuns(pl_fontRuns *fontRuns);
89 * Get the number of font runs.
91 * @param fontRuns is the <code>pl_fontRuns</code> object.
93 * @return the number of entries in the limit indices array.
97 U_INTERNAL le_int32 U_EXPORT2
98 pl_getFontRunCount(const pl_fontRuns *fontRuns);
101 * Reset the number of font runs to zero.
103 * @param fontRuns is the <code>pl_fontRuns</code> object.
107 U_INTERNAL void U_EXPORT2
108 pl_resetFontRuns(pl_fontRuns *fontRuns);
111 * Get the limit index for the last font run. This is the
112 * number of characters in the text.
114 * @param fontRuns is the <code>pl_fontRuns</code> object.
116 * @return the last limit index.
120 U_INTERNAL le_int32 U_EXPORT2
121 pl_getFontRunLastLimit(const pl_fontRuns *fontRuns);
124 * Get the limit index for a particular font run.
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.
129 * @return the limit index for the run, or -1 if <code>run</code> is out of bounds.
133 U_INTERNAL le_int32 U_EXPORT2
134 pl_getFontRunLimit(const pl_fontRuns *fontRuns,
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
142 * @param fontRuns is the <code>pl_fontRuns</code> object.
143 * @param run is the index into the font and limit indices arrays.
145 * @return the <code>le_font</code> associated with the given text run.
149 U_INTERNAL const le_font * U_EXPORT2
150 pl_getFontRunFont(const pl_fontRuns *fontRuns,
155 * Add a new font run to the given <code>pl_fontRuns</code> object.
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.
160 * @param fontRuns is the <code>pl_fontRuns</code> object.
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.
165 * @param limit is the limit index to add
167 * @return the run index where the font and limit index were stored, or -1 if
168 * the run cannot be added.
172 U_INTERNAL le_int32 U_EXPORT2
173 pl_addFontRun(pl_fontRuns *fontRuns,
178 * Construct a <code>pl_valueRuns</code> object from pre-existing arrays of values
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.
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.
187 * @param count is the number of entries in the two arrays.
191 U_INTERNAL pl_valueRuns * U_EXPORT2
192 pl_openValueRuns(const le_int32 *values,
193 const le_int32 *limits,
197 * Construct an empty <code>pl_valueRuns</code> object. Clients can add values and limits
198 * using the <code>pl_addValueRun</code> routine.
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.
203 * @see pl_addValueRun
207 U_INTERNAL pl_valueRuns * U_EXPORT2
208 pl_openEmptyValueRuns(le_int32 initialCapacity);
211 * Close the given <code>pl_valueRuns</code> object. Once this
212 * call returns, the object can no longer be referenced.
214 * @param valueRuns is the <code>pl_valueRuns</code> object.
218 U_INTERNAL void U_EXPORT2
219 pl_closeValueRuns(pl_valueRuns *valueRuns);
222 * Get the number of value runs.
224 * @param valueRuns is the <code>pl_valueRuns</code> object.
226 * @return the number of value runs.
230 U_INTERNAL le_int32 U_EXPORT2
231 pl_getValueRunCount(const pl_valueRuns *valueRuns);
234 * Reset the number of value runs to zero.
236 * @param valueRuns is the <code>pl_valueRuns</code> object.
240 U_INTERNAL void U_EXPORT2
241 pl_resetValueRuns(pl_valueRuns *valueRuns);
244 * Get the limit index for the last value run. This is the
245 * number of characters in the text.
247 * @param valueRuns is the <code>pl_valueRuns</code> object.
249 * @return the last limit index.
253 U_INTERNAL le_int32 U_EXPORT2
254 pl_getValueRunLastLimit(const pl_valueRuns *valueRuns);
257 * Get the limit index for a particular value run.
259 * @param valueRuns is the <code>pl_valueRuns</code> object.
260 * @param run is the run index.
262 * @return the limit index for the run, or -1 if <code>run</code> is out of bounds.
266 U_INTERNAL le_int32 U_EXPORT2
267 pl_getValueRunLimit(const pl_valueRuns *valueRuns,
271 * Get the value assoicated with the given run * of text. Use
272 * <code>pl_getValueRunLimit(run)</code> to get the corresponding
275 * @param valueRuns is the <code>pl_valueRuns</code> object.
276 * @param run is the run index.
278 * @return the value associated with the given text run.
282 U_INTERNAL le_int32 U_EXPORT2
283 pl_getValueRunValue(const pl_valueRuns *valueRuns,
288 * Add a new font run to the given <code>pl_valueRuns</code> object.
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.
293 * @param valueRuns is the <code>pl_valueRuns</code> object.
295 * @param value is the value to add.
297 * @param limit is the limit index to add
299 * @return the run index where the font and limit index were stored, or -1 if
300 * the run cannot be added.
304 U_INTERNAL le_int32 U_EXPORT2
305 pl_addValueRun(pl_valueRuns *valueRuns,
310 * Construct a <code>pl_localeRuns</code> object from pre-existing arrays of fonts
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.
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.
319 * @param count is the number of entries in the two arrays.
323 U_INTERNAL pl_localeRuns * U_EXPORT2
324 pl_openLocaleRuns(const char **locales,
325 const le_int32 *limits,
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.
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.
335 * @see pl_addLocaleRun
339 U_INTERNAL pl_localeRuns * U_EXPORT2
340 pl_openEmptyLocaleRuns(le_int32 initialCapacity);
343 * Close the given <code>pl_localeRuns</code> object. Once this
344 * call returns, the object can no longer be referenced.
346 * @param localeRuns is the <code>pl_localeRuns</code> object.
350 U_INTERNAL void U_EXPORT2
351 pl_closeLocaleRuns(pl_localeRuns *localeRuns);
354 * Get the number of font runs.
356 * @param localeRuns is the <code>pl_localeRuns</code> object.
358 * @return the number of entries in the limit indices array.
362 U_INTERNAL le_int32 U_EXPORT2
363 pl_getLocaleRunCount(const pl_localeRuns *localeRuns);
366 * Reset the number of locale runs to zero.
368 * @param localeRuns is the <code>pl_localeRuns</code> object.
372 U_INTERNAL void U_EXPORT2
373 pl_resetLocaleRuns(pl_localeRuns *localeRuns);
376 * Get the limit index for the last font run. This is the
377 * number of characters in the text.
379 * @param localeRuns is the <code>pl_localeRuns</code> object.
381 * @return the last limit index.
385 U_INTERNAL le_int32 U_EXPORT2
386 pl_getLocaleRunLastLimit(const pl_localeRuns *localeRuns);
389 * Get the limit index for a particular font run.
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.
394 * @return the limit index for the run, or -1 if <code>run</code> is out of bounds.
398 U_INTERNAL le_int32 U_EXPORT2
399 pl_getLocaleRunLimit(const pl_localeRuns *localeRuns,
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
407 * @param localeRuns is the <code>pl_localeRuns</code> object.
408 * @param run is the index into the font and limit indices arrays.
410 * @return the <code>le_font</code> associated with the given text run.
414 U_INTERNAL const char * U_EXPORT2
415 pl_getLocaleRunLocale(const pl_localeRuns *localeRuns,
420 * Add a new run to the given <code>pl_localeRuns</code> object.
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.
425 * @param localeRuns is the <code>pl_localeRuns</code> object.
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.
430 * @param limit is the limit index to add
432 * @return the run index where the font and limit index were stored, or -1 if
433 * the run cannot be added.
437 U_INTERNAL le_int32 U_EXPORT2
438 pl_addLocaleRun(pl_localeRuns *localeRuns,
442 #endif /* U_HIDE_INTERNAL_API */