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 associated 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 associated 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 associated 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