## Charsets and Surfaces

Charsets and Surfaces — Functions and macros for getting something sensible from EncaEncoding.

## Synopsis

    const char*         enca_charset_name                   (int charset,
                                                             EncaNameStyle whatname);
    const char**        enca_get_charset_aliases            (int charset,
                                                             size_t *n);
    char*               enca_get_surface_name               (EncaSurface surface,
                                                             EncaNameStyle whatname);
    EncaEncoding        enca_parse_encoding_name            (const char *name);
    EncaSurface         enca_charset_natural_surface        (int charset);
    EncaCharsetFlags    enca_charset_properties             (int charset);
    #define             enca_charset_is_7bit                (cs)
    #define             enca_charset_is_8bit                (cs)
    #define             enca_charset_is_16bit               (cs)
    #define             enca_charset_is_32bit               (cs)
    #define             enca_charset_is_fixed               (cs)
    #define             enca_charset_is_variable            (cs)
    #define             enca_charset_is_binary              (cs)
    #define             enca_charset_is_regular             (cs)
    #define             enca_charset_is_multibyte           (cs)
    #define             enca_charset_is_known               (cs)

## Description

## Details

### enca_charset_name ()

    const char*         enca_charset_name                   (int charset,
                                                             EncaNameStyle whatname);

Translates numeric charset id `charset` to some kind of name.

`charset` : | A charset id.
`whatname` : | Teh type of name you request.
Returns : | The requested charset name; NULL for invalid `whatname` or `charset`, or when `whatname` name doesn't exist for charset `charset` (ENCA_CS_UNKNOWN is OK).

### enca_get_charset_aliases ()

    const char**        enca_get_charset_aliases            (int charset,
                                                             size_t *n);

Returns list of accepted aliases for charset `charset`.

The list of aliases has to be freed by caller; the strings themselves must be considered constant and must NOT be freed.

`charset` : | A charset id.
`n` : | The number of aliases will be stored here.
Returns : | The list of aliases, storing their number into *`n`; NULL for invalid `charset` (*`n` is zero then).

### enca_get_surface_name ()

    char*               enca_get_surface_name               (EncaSurface surface,
                                                             EncaNameStyle whatname);

Constructs surface name from surface flags `surface`.

`surface` : | A surface.
`whatname` : | The type of name you request.
Returns : | The requested surface name; NULL for invalid `whatname`; empty string for naming style not supporting surfaces. In all cases, the returned string must be freed by caller when no longer used.

### enca_parse_encoding_name ()

    EncaEncoding        enca_parse_encoding_name            (const char *name);

Transofrms encoding specification charset/surface into numeric EncaEncoding.

When the charset name is not recognized, surfaces are not parsed at all and ENCA_CS_UNKNOWN is returned as charset. However, unrecognized surfaces are considered only a minor problem causing `ENCA_SURFACE_UNKNOWN` flag to be set in the result, beside recognized surface flags.

`name` : | An encoding specification.
Returns : | The charset/surface pair.

### enca_charset_natural_surface ()

    EncaSurface         enca_charset_natural_surface        (int charset);

Returns natural surface of a charset.

`charset` : | A charset.
Returns : | The requested charset natural surface (called `implied' in recode), zero for invalid `charset` or for charsets with no natural surface. Natrual surface is the surface one expects for a given charset -- e.g. CRLF EOLs for IBM/Microsoft charsets, CR EOLs for Macintosh charsets and LF EOLs for ISO/Unix charsets.

### enca_charset_properties ()

    EncaCharsetFlags    enca_charset_properties             (int charset);

Returns charset properties.

`charset` : | A charset.
Returns : | The requested charset properties; zero for invalid `charset`.

### enca_charset_is_7bit()

    #define             enca_charset_is_7bit(cs)

Expands to nonzero when characters are represented with 7bit characters.

`cs` : | Charset id.

### enca_charset_is_8bit()

    #define             enca_charset_is_8bit(cs)

Expands to nonzero when characters are represented with bytes.

`cs` : | Charset id.

### enca_charset_is_16bit()

    #define             enca_charset_is_16bit(cs)

Expands to nonzero when characters are represented with 2byte words.

`cs` : | Charset id.

### enca_charset_is_32bit()

    #define             enca_charset_is_32bit(cs)

Expands to nonzero when characters are represented with 4byte words.

`cs` : | Charset id.

### enca_charset_is_fixed()

    #define             enca_charset_is_fixed(cs)

Expands to nonzero when one characters consists of one fundamental piece.

`cs` : | Charset id.

### enca_charset_is_variable()

    #define             enca_charset_is_variable(cs)

Expands to nonzero when one character consists of variable number of fundamental pieces.

`cs` : | Charset id.

### enca_charset_is_binary()

    #define             enca_charset_is_binary(cs)

Expands to nonzero when charset is binary from ASCII viewpoint.

`cs` : | Charset id.

### enca_charset_is_regular()

    #define             enca_charset_is_regular(cs)

Expands to nonzero when charset is language dependent (8bit) charset.

`cs` : | Charset id.

### enca_charset_is_multibyte()

    #define             enca_charset_is_multibyte(cs)

Expands to nonzero when charset is multibyte.

`cs` : | Charset id.

### enca_charset_is_known()

    #define             enca_charset_is_known(cs)

Expands to nonzero when the charset is known (i.e. it's not ENCA_CS_UNKNOWN).

`cs` : | Charset id.