## gwyentities

gwyentities — Transform SGML-like symbol entities to UTF-8

## Synopsis

    #include <libgwyddion/gwyddion.h>

                        GwyTextEntity;
    GwyInventory*       gwy_entities                        (void);
    const gchar*        gwy_entities_entity_to_utf8         (const gchar *entity);
    gchar*              gwy_entities_text_to_utf8           (const gchar *text);

## Description

A subset of named SGML-like symbol entities (e.g. `&alpha;`), to be used namely in GwySciText.

Function `gwy_entities_entity_to_utf8()` converts a signle entity to UTF-8. Function `gwy_entities_text_to_utf8()` converts a text containing entities to UTF-8. An GwyInventory with all available entities can be obtained with `gwy_entities()`.

## Details

### GwyTextEntity

    typedef struct {
        const gchar *entity;
        const gchar *utf8;
    } GwyTextEntity;

The type of text entity data.

const gchar *`entity`; | Bare entity name, without the leading ampersand and trailing semicolon.
const gchar *`utf8`; | The corresponding character, in UTF-8.

### gwy_entities ()

    GwyInventory*       gwy_entities                        (void);

Returns a constant inventory with all available entities.

Returns : | The entities as a GwyInventory.

### gwy_entities_entity_to_utf8 ()

    const gchar*        gwy_entities_entity_to_utf8         (const gchar *entity);

Converts a single named entity `entity` to UTF-8 representation.

The string passed to this function should be a bare entity name, i.e. it should not contain the ampersand and semicolon.

`entity` : | A single entity name, as a nul-delimited string.
Returns : | `entity` if the name was not recognized, or a valid UTF-8 string. If the returned string is not equal to `entities`, it's owned by entities and must not be freed nor modified.

### gwy_entities_text_to_utf8 ()

    gchar*              gwy_entities_text_to_utf8           (const gchar *text);

Converts entities in a text to UTF-8.

`text` : | A nul-delimited string.
Returns : | A newly allocated nul-delimited string containing the converted text.