# plruns.h File Reference

C API for run arrays. More...

`#include "unicode/utypes.h"`
`#include "unicode/ubidi.h"`
`#include "layout/LETypes.h"`
`#include "layout/loengine.h"`

Go to the source code of this file.

## Typedefs
typedef void | pl_fontRuns
| Opaque datatype representing an array of font runs.
typedef void | pl_valueRuns
| Opaque datatype representing an array of value runs.
typedef void | pl_localeRuns
| Opaque datatype representing an array of locale runs.
## Functions
pl_fontRuns * | pl_openFontRuns (const le_font **fonts, const le_int32 *limits, le_int32 count)
| Construct a `pl_fontRuns` object from pre-existing arrays of fonts and limit indices.
pl_fontRuns * | pl_openEmptyFontRuns (le_int32 initialCapacity)
| Construct an empty `pl_fontRuns` object.
void | pl_closeFontRuns (pl_fontRuns *fontRuns)
| Close the given `pl_fontRuns` object.
le_int32 | pl_getFontRunCount (const pl_fontRuns *fontRuns)
| Get the number of font runs.
void | pl_resetFontRuns (pl_fontRuns *fontRuns)
| Reset the number of font runs to zero.
le_int32 | pl_getFontRunLastLimit (const pl_fontRuns *fontRuns)
| Get the limit index for the last font run.
le_int32 | pl_getFontRunLimit (const pl_fontRuns *fontRuns, le_int32 run)
| Get the limit index for a particular font run.
const le_font * | pl_getFontRunFont (const pl_fontRuns *fontRuns, le_int32 run)
| Get the `le_font` object assoicated with the given run of text.
le_int32 | pl_addFontRun (pl_fontRuns *fontRuns, const le_font *font, le_int32 limit)
| Add a new font run to the given `pl_fontRuns` object.
pl_valueRuns * | pl_openValueRuns (const le_int32 *values, const le_int32 *limits, le_int32 count)
| Construct a `pl_valueRuns` object from pre-existing arrays of values and limit indices.
pl_valueRuns * | pl_openEmptyValueRuns (le_int32 initialCapacity)
| Construct an empty `pl_valueRuns` object.
void | pl_closeValueRuns (pl_valueRuns *valueRuns)
| Close the given `pl_valueRuns` object.
le_int32 | pl_getValueRunCount (const pl_valueRuns *valueRuns)
| Get the number of value runs.
void | pl_resetValueRuns (pl_valueRuns *valueRuns)
| Reset the number of value runs to zero.
le_int32 | pl_getValueRunLastLimit (const pl_valueRuns *valueRuns)
| Get the limit index for the last value run.
le_int32 | pl_getValueRunLimit (const pl_valueRuns *valueRuns, le_int32 run)
| Get the limit index for a particular value run.
le_int32 | pl_getValueRunValue (const pl_valueRuns *valueRuns, le_int32 run)
| Get the value assoicated with the given run * of text.
le_int32 | pl_addValueRun (pl_valueRuns *valueRuns, le_int32 value, le_int32 limit)
| Add a new font run to the given `pl_valueRuns` object.
pl_localeRuns * | pl_openLocaleRuns (const char **locales, const le_int32 *limits, le_int32 count)
| Construct a `pl_localeRuns` object from pre-existing arrays of fonts and limit indices.
pl_localeRuns * | pl_openEmptyLocaleRuns (le_int32 initialCapacity)
| Construct an empty `pl_localeRuns` object.
void | pl_closeLocaleRuns (pl_localeRuns *localeRuns)
| Close the given `pl_localeRuns` object.
le_int32 | pl_getLocaleRunCount (const pl_localeRuns *localeRuns)
| Get the number of font runs.
void | pl_resetLocaleRuns (pl_localeRuns *localeRuns)
| Reset the number of locale runs to zero.
le_int32 | pl_getLocaleRunLastLimit (const pl_localeRuns *localeRuns)
| Get the limit index for the last font run.
le_int32 | pl_getLocaleRunLimit (const pl_localeRuns *localeRuns, le_int32 run)
| Get the limit index for a particular font run.
const char * | pl_getLocaleRunLocale (const pl_localeRuns *localeRuns, le_int32 run)
| Get the `le_font` object assoicated with the given run of text.
le_int32 | pl_addLocaleRun (pl_localeRuns *localeRuns, const char *locale, le_int32 limit)
| Add a new run to the given `pl_localeRuns` object.

## Detailed Description

C API for run arrays.

This is a technology preview. The API may change significantly.

Definition in file plruns.h.

## Function Documentation

le_int32 pl_addFontRun | ( | pl_fontRuns * | fontRuns,
|  | const le_font * | font,
|  | le_int32 | limit |
| ) |  |  |

Add a new font run to the given `pl_fontRuns` object.

If the `pl_fontRuns` object was not created by calling `pl_openEmptyFontRuns`, this method will return a run index of -1.

Parameters:

  | fontRuns | is the `pl_fontRuns` object.
  | font | is the address of the `le_font` to add. This object must remain valid until the `pl_fontRuns` object is closed.
  | limit | is the limit index to add

Returns:
  the run index where the font and limit index were stored, or -1 if the run cannot be added.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_addLocaleRun | ( | pl_localeRuns * | localeRuns,
|  | const char * | locale,
|  | le_int32 | limit |
| ) |  |  |

Add a new run to the given `pl_localeRuns` object.

If the `pl_localeRuns` object was not created by calling `pl_openEmptyLocaleRuns`, this method will return a run index of -1.

Parameters:

  | localeRuns | is the `pl_localeRuns` object.
  | locale | is the name of the locale to add. This name must remain valid until the `pl_localeRuns` object is closed.
  | limit | is the limit index to add

Returns:
  the run index where the font and limit index were stored, or -1 if the run cannot be added.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_addValueRun | ( | pl_valueRuns * | valueRuns,
|  | le_int32 | value,
|  | le_int32 | limit |
| ) |  |  |

Add a new font run to the given `pl_valueRuns` object.

If the `pl_valueRuns` object was not created by calling `pl_openEmptyFontRuns`, this method will return a run index of -1.

Parameters:

  | valueRuns | is the `pl_valueRuns` object.
  | value | is the value to add.
  | limit | is the limit index to add

Returns:
  the run index where the font and limit index were stored, or -1 if the run cannot be added.

Internal:
  Do not use. This API is for internal use only.

void pl_closeFontRuns | ( | pl_fontRuns * | fontRuns | ) |

Close the given `pl_fontRuns` object.

Once this call returns, the object can no longer be referenced.

Parameters:

  | fontRuns | is the `pl_fontRuns` object.

Internal:
  Do not use. This API is for internal use only.

void pl_closeLocaleRuns | ( | pl_localeRuns * | localeRuns | ) |

Close the given `pl_localeRuns` object.

Once this call returns, the object can no longer be referenced.

Parameters:

  | localeRuns | is the `pl_localeRuns` object.

Internal:
  Do not use. This API is for internal use only.

void pl_closeValueRuns | ( | pl_valueRuns * | valueRuns | ) |

Close the given `pl_valueRuns` object.

Once this call returns, the object can no longer be referenced.

Parameters:

  | valueRuns | is the `pl_valueRuns` object.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_getFontRunCount | ( | const pl_fontRuns * | fontRuns | ) |

Get the number of font runs.

Parameters:

  | fontRuns | is the `pl_fontRuns` object.

Returns:
  the number of entries in the limit indices array.

Internal:
  Do not use. This API is for internal use only.

const le_font* pl_getFontRunFont | ( | const pl_fontRuns * | fontRuns,
|  | le_int32 | run |
| ) |  |  |

Get the `le_font` object assoicated with the given run of text.

Use `pl_getFontRunLimit(run)` to get the corresponding limit index.

Parameters:

  | fontRuns | is the `pl_fontRuns` object.
  | run | is the index into the font and limit indices arrays.

Returns:
  the `le_font` associated with the given text run.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_getFontRunLastLimit | ( | const pl_fontRuns * | fontRuns | ) |

Get the limit index for the last font run.

This is the number of characters in the text.

Parameters:

  | fontRuns | is the `pl_fontRuns` object.

Returns:
  the last limit index.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_getFontRunLimit | ( | const pl_fontRuns * | fontRuns,
|  | le_int32 | run |
| ) |  |  |

Get the limit index for a particular font run.

Parameters:

  | fontRuns | is the `pl_fontRuns` object.
  | run | is the run. This is an index into the limit index array.

Returns:
  the limit index for the run, or -1 if `run` is out of bounds.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_getLocaleRunCount | ( | const pl_localeRuns * | localeRuns | ) |

Get the number of font runs.

Parameters:

  | localeRuns | is the `pl_localeRuns` object.

Returns:
  the number of entries in the limit indices array.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_getLocaleRunLastLimit | ( | const pl_localeRuns * | localeRuns | ) |

Get the limit index for the last font run.

This is the number of characters in the text.

Parameters:

  | localeRuns | is the `pl_localeRuns` object.

Returns:
  the last limit index.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_getLocaleRunLimit | ( | const pl_localeRuns * | localeRuns,
|  | le_int32 | run |
| ) |  |  |

Get the limit index for a particular font run.

Parameters:

  | localeRuns | is the `pl_localeRuns` object.
  | run | is the run. This is an index into the limit index array.

Returns:
  the limit index for the run, or -1 if `run` is out of bounds.

Internal:
  Do not use. This API is for internal use only.

const char* pl_getLocaleRunLocale | ( | const pl_localeRuns * | localeRuns,
|  | le_int32 | run |
| ) |  |  |

Get the `le_font` object assoicated with the given run of text.

Use `pl_getLocaleRunLimit(run)` to get the corresponding limit index.

Parameters:

  | localeRuns | is the `pl_localeRuns` object.
  | run | is the index into the font and limit indices arrays.

Returns:
  the `le_font` associated with the given text run.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_getValueRunCount | ( | const pl_valueRuns * | valueRuns | ) |

Get the number of value runs.

Parameters:

  | valueRuns | is the `pl_valueRuns` object.

Returns:
  the number of value runs.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_getValueRunLastLimit | ( | const pl_valueRuns * | valueRuns | ) |

Get the limit index for the last value run.

This is the number of characters in the text.

Parameters:

  | valueRuns | is the `pl_valueRuns` object.

Returns:
  the last limit index.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_getValueRunLimit | ( | const pl_valueRuns * | valueRuns,
|  | le_int32 | run |
| ) |  |  |

Get the limit index for a particular value run.

Parameters:

  | valueRuns | is the `pl_valueRuns` object.
  | run | is the run index.

Returns:
  the limit index for the run, or -1 if `run` is out of bounds.

Internal:
  Do not use. This API is for internal use only.

le_int32 pl_getValueRunValue | ( | const pl_valueRuns * | valueRuns,
|  | le_int32 | run |
| ) |  |  |

Get the value assoicated with the given run * of text.

Use `pl_getValueRunLimit(run)` to get the corresponding limit index.

Parameters:

  | valueRuns | is the `pl_valueRuns` object.
  | run | is the run index.

Returns:
  the value associated with the given text run.

Internal:
  Do not use. This API is for internal use only.

pl_fontRuns* pl_openEmptyFontRuns | ( | le_int32 | initialCapacity | ) |

Construct an empty `pl_fontRuns` object.

Clients can add font and limit indices arrays using the `pl_addFontRun` routine.

Parameters:

  | initialCapacity | is the initial size of the font and limit indices arrays. If this value is zero, no arrays will be allocated.

See also:
  pl_addFontRun

Internal:
  Do not use. This API is for internal use only.

pl_localeRuns* pl_openEmptyLocaleRuns | ( | le_int32 | initialCapacity | ) |

Construct an empty `pl_localeRuns` object.

Clients can add font and limit indices arrays using the `pl_addFontRun` routine.

Parameters:

  | initialCapacity | is the initial size of the font and limit indices arrays. If this value is zero, no arrays will be allocated.

See also:
  pl_addLocaleRun

Internal:
  Do not use. This API is for internal use only.

pl_valueRuns* pl_openEmptyValueRuns | ( | le_int32 | initialCapacity | ) |

Construct an empty `pl_valueRuns` object.

Clients can add values and limits using the `pl_addValueRun` routine.

Parameters:

  | initialCapacity | is the initial size of the value and limit indices arrays. If this value is zero, no arrays will be allocated.

See also:
  pl_addValueRun

Internal:
  Do not use. This API is for internal use only.

pl_fontRuns* pl_openFontRuns | ( | const le_font ** | fonts,
|  | const le_int32 * | limits,
|  | le_int32 | count |
| ) |  |  |

Construct a `pl_fontRuns` object from pre-existing arrays of fonts and limit indices.

Parameters:

  | fonts | is the address of an array of pointers to `le_font` objects. This array, and the `le_font` objects to which it points must remain valid until the `pl_fontRuns` object is closed.
  | limits | is the address of an array of limit indices. This array must remain valid until the `pl_fontRuns` object is closed.
  | count | is the number of entries in the two arrays.

Internal:
  Do not use. This API is for internal use only.

pl_localeRuns* pl_openLocaleRuns | ( | const char ** | locales,
|  | const le_int32 * | limits,
|  | le_int32 | count |
| ) |  |  |

Construct a `pl_localeRuns` object from pre-existing arrays of fonts and limit indices.

Parameters:

  | locales | is the address of an array of pointers to locale name strings. This array must remain valid until the `pl_localeRuns` object is destroyed.
  | limits | is the address of an array of limit indices. This array must remain valid until the `pl_valueRuns` object is destroyed.
  | count | is the number of entries in the two arrays.

Internal:
  Do not use. This API is for internal use only.

pl_valueRuns* pl_openValueRuns | ( | const le_int32 * | values,
|  | const le_int32 * | limits,
|  | le_int32 | count |
| ) |  |  |

Construct a `pl_valueRuns` object from pre-existing arrays of values and limit indices.

Parameters:

  | values | is the address of an array of values. This array must remain valid until the `pl_valueRuns` object is closed.
  | limits | is the address of an array of limit indices. This array must remain valid until the `pl_valueRuns` object is closed.
  | count | is the number of entries in the two arrays.

Internal:
  Do not use. This API is for internal use only.

void pl_resetFontRuns | ( | pl_fontRuns * | fontRuns | ) |

Reset the number of font runs to zero.

Parameters:

  | fontRuns | is the `pl_fontRuns` object.

Internal:
  Do not use. This API is for internal use only.

void pl_resetLocaleRuns | ( | pl_localeRuns * | localeRuns | ) |

Reset the number of locale runs to zero.

Parameters:

  | localeRuns | is the `pl_localeRuns` object.

Internal:
  Do not use. This API is for internal use only.

void pl_resetValueRuns | ( | pl_valueRuns * | valueRuns | ) |

Reset the number of value runs to zero.

Parameters:

  | valueRuns | is the `pl_valueRuns` object.

Internal:
  Do not use. This API is for internal use only.