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