Pango Reference Manual: Coverage Maps

## Coverage Maps Coverage Maps — Unicode character range coverage storage |

## Functions

#define | PANGO_TYPE_COVERAGE_LEVEL
PangoCoverage * | pango_coverage_new ()
PangoCoverage * | pango_coverage_ref ()
void | pango_coverage_unref ()
PangoCoverage * | pango_coverage_copy ()
PangoCoverageLevel | pango_coverage_get ()
void | pango_coverage_max ()
void | pango_coverage_set ()
void | pango_coverage_to_bytes ()
PangoCoverage * | pango_coverage_from_bytes ()

## Types and Values

enum | PangoCoverageLevel
| PangoCoverage

## Object Hierarchy

        GEnum
        ╰── PangoCoverageLevel

## Description

It is often necessary in Pango to determine if a particular font can represent a particular character, and also how well it can represent that character. The PangoCoverage is a data structure that is used to represent that information.

## Functions

### PANGO_TYPE_COVERAGE_LEVEL

    #define PANGO_TYPE_COVERAGE_LEVEL (pango_coverage_level_get_type ())

### pango_coverage_new ()

    PangoCoverage *
    pango_coverage_new (void);

Create a new PangoCoverage

#### Returns

the newly allocated PangoCoverage, initialized to `PANGO_COVERAGE_NONE` with a reference count of one, which should be freed with `pango_coverage_unref()`.

### pango_coverage_ref ()

    PangoCoverage *
    pango_coverage_ref (PangoCoverage *coverage);

Increase the reference count on the PangoCoverage by one

#### Parameters

coverage | a PangoCoverage |

#### Returns

`coverage`

### pango_coverage_unref ()

    void
    pango_coverage_unref (PangoCoverage *coverage);

Decrease the reference count on the PangoCoverage by one. If the result is zero, free the coverage and all associated memory.

#### Parameters

coverage | a PangoCoverage |

### pango_coverage_copy ()

    PangoCoverage *
    pango_coverage_copy (PangoCoverage *coverage);

Copy an existing PangoCoverage. (This function may now be unnecessary since we refcount the structure. File a bug if you use it.)

#### Parameters

coverage | a PangoCoverage |

#### Returns

the newly allocated PangoCoverage, with a reference count of one, which should be freed with `pango_coverage_unref()`.

[transfer full]

### pango_coverage_get ()

    PangoCoverageLevel
    pango_coverage_get (PangoCoverage *coverage,
                        int index_);

Determine whether a particular index is covered by `coverage`

#### Parameters

coverage | a PangoCoverage |
index_ | the index to check |

#### Returns

the coverage level of `coverage` for character `index_` .

### pango_coverage_max ()

    void
    pango_coverage_max (PangoCoverage *coverage,
                        PangoCoverage *other);

Set the coverage for each index in `coverage` to be the max (better) value of the current coverage for the index and the coverage for the corresponding index in `other` .

#### Parameters

coverage | a PangoCoverage |
other | another PangoCoverage |

### pango_coverage_set ()

    void
    pango_coverage_set (PangoCoverage *coverage,
                        int index_,
                        PangoCoverageLevel level);

Modify a particular index within `coverage`

#### Parameters

coverage | a PangoCoverage |
index_ | the index to modify |
level | the new level for `index_` |

### pango_coverage_to_bytes ()

    void
    pango_coverage_to_bytes (PangoCoverage *coverage,
                             guchar **bytes,
                             int *n_bytes);

Convert a PangoCoverage structure into a flat binary format

#### Parameters

coverage | a PangoCoverage |
bytes | location to store result (must be freed with `g_free()`). | [out][array length=n_bytes][element-type guint8]
n_bytes | location to store size of result. | [out]

### pango_coverage_from_bytes ()

    PangoCoverage *
    pango_coverage_from_bytes (guchar *bytes,
                               int n_bytes);

Convert data generated from `pango_coverage_to_bytes()` back to a PangoCoverage

#### Parameters

bytes | binary data representing a PangoCoverage. | [array length=n_bytes][element-type guint8]
n_bytes | the size of `bytes` in bytes |

#### Returns

a newly allocated PangoCoverage, or `NULL` if the data was invalid.

[transfer full]

## Types and Values

### enum PangoCoverageLevel

Used to indicate how well a font can represent a particular Unicode character point for a particular script.

#### Members

PANGO_COVERAGE_NONE | The character is not representable with the font. |
PANGO_COVERAGE_FALLBACK | The character is represented in a way that may be comprehensible but is not the correct graphical form. For instance, a Hangul character represented as a a sequence of Jamos, or a Latin transliteration of a Cyrillic word. |
PANGO_COVERAGE_APPROXIMATE | The character is represented as basically the correct graphical form, but with a stylistic variant inappropriate for the current script. |
PANGO_COVERAGE_EXACT | The character is represented as the correct graphical form. |

### PangoCoverage

    typedef struct _PangoCoverage PangoCoverage;

The PangoCoverage structure represents a map from Unicode characters to PangoCoverageLevel. It is an opaque structure with no public fields.