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. More...
typedef void | pl_valueRuns
| Opaque datatype representing an array of value runs. More...
typedef void | pl_localeRuns
| Opaque datatype representing an array of locale runs. More...

## Functions

U_CAPI 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. More...
U_CAPI pl_fontRuns * | pl_openEmptyFontRuns (le_int32 initialCapacity)
| Construct an empty `pl_fontRuns` object. More...
U_CAPI void | pl_closeFontRuns (pl_fontRuns *fontRuns)
| Close the given `pl_fontRuns` object. More...
U_CAPI le_int32 | pl_getFontRunCount (const pl_fontRuns *fontRuns)
| Get the number of font runs. More...
U_CAPI void | pl_resetFontRuns (pl_fontRuns *fontRuns)
| Reset the number of font runs to zero. More...
U_CAPI le_int32 | pl_getFontRunLastLimit (const pl_fontRuns *fontRuns)
| Get the limit index for the last font run. More...
U_CAPI le_int32 | pl_getFontRunLimit (const pl_fontRuns *fontRuns, le_int32 run)
| Get the limit index for a particular font run. More...
U_CAPI const le_font * | pl_getFontRunFont (const pl_fontRuns *fontRuns, le_int32 run)
| Get the `le_font` object associated with the given run of text. More...
U_CAPI 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. More...
U_CAPI 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. More...
U_CAPI pl_valueRuns * | pl_openEmptyValueRuns (le_int32 initialCapacity)
| Construct an empty `pl_valueRuns` object. More...
U_CAPI void | pl_closeValueRuns (pl_valueRuns *valueRuns)
| Close the given `pl_valueRuns` object. More...
U_CAPI le_int32 | pl_getValueRunCount (const pl_valueRuns *valueRuns)
| Get the number of value runs. More...
U_CAPI void | pl_resetValueRuns (pl_valueRuns *valueRuns)
| Reset the number of value runs to zero. More...
U_CAPI le_int32 | pl_getValueRunLastLimit (const pl_valueRuns *valueRuns)
| Get the limit index for the last value run. More...
U_CAPI le_int32 | pl_getValueRunLimit (const pl_valueRuns *valueRuns, le_int32 run)
| Get the limit index for a particular value run. More...
U_CAPI le_int32 | pl_getValueRunValue (const pl_valueRuns *valueRuns, le_int32 run)
| Get the value associated with the given run * of text. More...
U_CAPI le_int32 | pl_addValueRun (pl_valueRuns *valueRuns, le_int32 value, le_int32 limit)
| Add a new font run to the given `pl_valueRuns` object. More...
U_CAPI 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. More...
U_CAPI pl_localeRuns * | pl_openEmptyLocaleRuns (le_int32 initialCapacity)
| Construct an empty `pl_localeRuns` object. More...
U_CAPI void | pl_closeLocaleRuns (pl_localeRuns *localeRuns)
| Close the given `pl_localeRuns` object. More...
U_CAPI le_int32 | pl_getLocaleRunCount (const pl_localeRuns *localeRuns)
| Get the number of font runs. More...
U_CAPI void | pl_resetLocaleRuns (pl_localeRuns *localeRuns)
| Reset the number of locale runs to zero. More...
U_CAPI le_int32 | pl_getLocaleRunLastLimit (const pl_localeRuns *localeRuns)
| Get the limit index for the last font run. More...
U_CAPI le_int32 | pl_getLocaleRunLimit (const pl_localeRuns *localeRuns, le_int32 run)
| Get the limit index for a particular font run. More...
U_CAPI const char * | pl_getLocaleRunLocale (const pl_localeRuns *localeRuns, le_int32 run)
| Get the `le_font` object associated with the given run of text. More...
U_CAPI le_int32 | pl_addLocaleRun (pl_localeRuns *localeRuns, const char *locale, le_int32 limit)
| Add a new run to the given `pl_localeRuns` object. More...

## Detailed Description

C API for run arrays.

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

Definition in file plruns.h.

## Typedef Documentation

## pl_fontRuns

typedef void pl_fontRuns

Opaque datatype representing an array of font runs.

Internal:
  Do not use.

This API is for internal use only.

Definition at line 25 of file plruns.h.

## pl_localeRuns

typedef void pl_localeRuns

Opaque datatype representing an array of locale runs.

Internal:
  Do not use.

This API is for internal use only.

Definition at line 35 of file plruns.h.

## pl_valueRuns

typedef void pl_valueRuns

Opaque datatype representing an array of value runs.

Internal:
  Do not use.

This API is for internal use only.

Definition at line 30 of file plruns.h.

## Function Documentation

## pl_addFontRun()

U_CAPI 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.

## pl_addLocaleRun()

U_CAPI 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.

## pl_addValueRun()

U_CAPI 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.

## pl_closeFontRuns()

U_CAPI 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.

## pl_closeLocaleRuns()

U_CAPI 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.

## pl_closeValueRuns()

U_CAPI 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.

## pl_getFontRunCount()

U_CAPI 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.

## pl_getFontRunFont()

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

Get the `le_font` object associated 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.

## pl_getFontRunLastLimit()

U_CAPI 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.

## pl_getFontRunLimit()

U_CAPI 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.

## pl_getLocaleRunCount()

U_CAPI 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.

## pl_getLocaleRunLastLimit()

U_CAPI 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.

## pl_getLocaleRunLimit()

U_CAPI 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.

## pl_getLocaleRunLocale()

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

Get the `le_font` object associated 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.

## pl_getValueRunCount()

U_CAPI 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.

## pl_getValueRunLastLimit()

U_CAPI 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.

## pl_getValueRunLimit()

U_CAPI 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.

## pl_getValueRunValue()

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

Get the value associated 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_openEmptyFontRuns()

U_CAPI 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_openEmptyLocaleRuns()

U_CAPI 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_openEmptyValueRuns()

U_CAPI 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_openFontRuns()

U_CAPI 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_openLocaleRuns()

U_CAPI 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_openValueRuns()

U_CAPI 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.

## pl_resetFontRuns()

U_CAPI 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.

## pl_resetLocaleRuns()

U_CAPI 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.

## pl_resetValueRuns()

U_CAPI 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.