## Coverage Maps

Coverage Maps — Unicode character range coverage storage

## Synopsis

    enum                PangoCoverageLevel;
    #define             PANGO_TYPE_COVERAGE_LEVEL
                        PangoCoverage;

    PangoCoverage *     pango_coverage_new                  (void);
    PangoCoverage *     pango_coverage_ref                  (PangoCoverage *coverage);
    void                pango_coverage_unref                (PangoCoverage *coverage);
    PangoCoverage *     pango_coverage_copy                 (PangoCoverage *coverage);
    PangoCoverageLevel  pango_coverage_get                  (PangoCoverage *coverage,
                                                             int index_);
    void                pango_coverage_max                  (PangoCoverage *coverage,
                                                             PangoCoverage *other);
    void                pango_coverage_set                  (PangoCoverage *coverage,
                                                             int index_,
                                                             PangoCoverageLevel level);
    void                pango_coverage_to_bytes             (PangoCoverage *coverage,
                                                             guchar **bytes,
                                                             int *n_bytes);
    PangoCoverage *     pango_coverage_from_bytes           (guchar *bytes,
                                                             int n_bytes);

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

## Details

### enum PangoCoverageLevel

    typedef enum {
      PANGO_COVERAGE_NONE,
      PANGO_COVERAGE_FALLBACK,
      PANGO_COVERAGE_APPROXIMATE,
      PANGO_COVERAGE_EXACT
    } PangoCoverageLevel;

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

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

### PANGO_TYPE_COVERAGE_LEVEL

    #define PANGO_TYPE_COVERAGE_LEVEL (pango_coverage_level_get_type())

The GObject type for PangoCoverageLevel.

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

### 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

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

`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.)

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

### pango_coverage_get ()

    PangoCoverageLevel  pango_coverage_get                  (PangoCoverage *coverage,
                                                             int index_);

Determine whether a particular index is covered by `coverage`

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

`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`

`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

`coverage` : | a PangoCoverage
`bytes` : | location to store result (must be freed with `g_free()`)
`n_bytes` : | location to store size of result

### pango_coverage_from_bytes ()

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

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

`bytes` : | binary data representing a PangoCoverage
`n_bytes` : | the size of `bytes` in bytes
Returns : | a newly allocated PangoCoverage, or `NULL` if the data was invalid.