TeplEncoding: Tepl 4 Reference Manual

## TeplEncoding TeplEncoding — Character encoding |

## Functions

TeplEncoding * | tepl_encoding_new ()
TeplEncoding * | tepl_encoding_new_utf8 ()
TeplEncoding * | tepl_encoding_new_from_locale ()
TeplEncoding * | tepl_encoding_copy ()
void | tepl_encoding_free ()
const gchar * | tepl_encoding_get_charset ()
const gchar * | tepl_encoding_get_name ()
gchar * | tepl_encoding_to_string ()
gboolean | tepl_encoding_is_utf8 ()
gboolean | tepl_encoding_equals ()
GSList * | tepl_encoding_get_all ()
GSList * | tepl_encoding_get_default_candidates ()

## Types and Values

| TeplEncoding

## Object Hierarchy

        GBoxed
        ╰── TeplEncoding

## Includes

    #include <tepl/tepl.h>

## Description

The TeplEncoding boxed type represents a character encoding. It is used for example by TeplFile. Note that the text in GTK widgets is always encoded in UTF-8.

TeplEncoding is a fork of GtkSourceEncoding with a different API to accommodate the new TeplFileLoader implementation.

## Functions

### tepl_encoding_new ()

    TeplEncoding *
    tepl_encoding_new (const gchar *charset);

Creates a new TeplEncoding from a character set such as "UTF-8" or "ISO-8859-1".

The `tepl_encoding_get_charset()` function will return exactly the same string as the `charset` passed in to this constructor.

#### Parameters

charset | a character set. |

#### Returns

the new TeplEncoding. Free with `tepl_encoding_free()`.

Since: 2.0

### tepl_encoding_new_utf8 ()

    TeplEncoding *
    tepl_encoding_new_utf8 (void);

Creates a new TeplEncoding with the "UTF-8" character set.

#### Returns

the new TeplEncoding. Free with `tepl_encoding_free()`.

Since: 2.0

### tepl_encoding_new_from_locale ()

    TeplEncoding *
    tepl_encoding_new_from_locale (void);

Creates a new TeplEncoding from the current locale, as returned by `g_get_charset()`.

#### Returns

the new TeplEncoding. Free with `tepl_encoding_free()`.

Since: 2.0

### tepl_encoding_copy ()

    TeplEncoding *
    tepl_encoding_copy (const TeplEncoding *enc);

#### Parameters

enc | a TeplEncoding. |

#### Returns

a copy of `enc` .

[transfer full]

Since: 2.0

### tepl_encoding_free ()

    void
    tepl_encoding_free (TeplEncoding *enc);

#### Parameters

enc | a TeplEncoding, or `NULL`. | [nullable]

Since: 2.0

### tepl_encoding_get_charset ()

    const gchar *
    tepl_encoding_get_charset (const TeplEncoding *enc);

Gets the character set of the TeplEncoding, such as "UTF-8" or "ISO-8859-1".

#### Parameters

enc | a TeplEncoding. |

#### Returns

the character set of the TeplEncoding.

Since: 2.0

### tepl_encoding_get_name ()

    const gchar *
    tepl_encoding_get_name (const TeplEncoding *enc);

Gets the name of the TeplEncoding such as "Unicode" or "Western". If the charset is unknown by TeplEncoding, "Unknown" is returned. The return value is already translated by gettext.

#### Parameters

enc | a TeplEncoding. |

#### Returns

the name of the TeplEncoding.

Since: 2.0

### tepl_encoding_to_string ()

    gchar *
    tepl_encoding_to_string (const TeplEncoding *enc);

Returns the encoding name with the charset in parenthesis, for example "Unicode (UTF-8)". If the name is unknown, just the charset is returned. The name is translated by gettext.

#### Parameters

enc | a TeplEncoding. |

#### Returns

a string representation. Free with `g_free()` when no longer needed.

Since: 2.0

### tepl_encoding_is_utf8 ()

    gboolean
    tepl_encoding_is_utf8 (const TeplEncoding *enc);

Returns whether `enc` is a UTF-8 encoding.

If `enc` was created with `tepl_encoding_new_utf8()`, the charset is "UTF-8". But iconv supports other variants: "UTF8", "utf-8" and "utf8". This function returns `TRUE` for all UTF-8 variants supported by iconv.

#### Parameters

enc | a TeplEncoding. |

#### Returns

whether `enc` is a UTF-8 encoding.

Since: 2.0

### tepl_encoding_equals ()

    gboolean
    tepl_encoding_equals (const TeplEncoding *enc1,
                          const TeplEncoding *enc2);

Returns whether `enc1` and `enc2` are equal. It returns `TRUE` iff:

- Both `enc1` and `enc2` are `NULL`;

- Or both `enc1` and `enc2` have a UTF-8 charset (see `tepl_encoding_is_utf8()`);

- Or the charsets are equal according to `g_ascii_strcasecmp()` (because iconv-compatible charsets are case insensitive).

#### Parameters

enc1 | a TeplEncoding, or `NULL`. | [nullable]
enc2 | a TeplEncoding, or `NULL`. | [nullable]

#### Returns

whether `enc1` and `enc2` are equal.

Since: 2.0

### tepl_encoding_get_all ()

    GSList *
    tepl_encoding_get_all (void);

Gets a list of all encodings known by TeplEncoding.

#### Returns

a list of TeplEncoding's.

[transfer full][element-type TeplEncoding]

Since: 2.0

### tepl_encoding_get_default_candidates ()

    GSList *
    tepl_encoding_get_default_candidates (void);

Gets the list of default candidate encodings to try when loading a file. See `gtk_source_file_loader_set_candidate_encodings()`.

This function returns a different list depending on the current locale (i.e. language, country and default encoding). The UTF-8 encoding and the current locale encoding are guaranteed to be present in the returned list.

Note that the returned list doesn't contain all encodings known by TeplEncoding, it is a limited list that contains only the encodings that have the most likelihood to fit for the current locale.

#### Returns

the list of default candidate encodings.

[transfer full][element-type TeplEncoding]

Since: 2.0

## Types and Values

### TeplEncoding

    typedef struct _TeplEncoding TeplEncoding;

## See Also

TeplFileSaver, TeplFileLoader