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