## Container - Tag

Container - Tag — A container class for Language tag

## Functions

lt_tag_t * | lt_tag_new ()
lt_tag_t * | lt_tag_ref ()
void | lt_tag_unref ()
lt_bool_t | lt_tag_parse ()
lt_bool_t | lt_tag_parse_with_extra_token ()
void | lt_tag_clear ()
lt_tag_t * | lt_tag_copy ()
lt_bool_t | lt_tag_truncate ()
const char * | lt_tag_get_string_with_filter ()
const char * | lt_tag_get_string ()
char * | lt_tag_canonicalize ()
char * | lt_tag_canonicalize_in_extlang_form ()
char * | lt_tag_convert_to_locale ()
lt_tag_t * | lt_tag_convert_from_locale ()
lt_tag_t * | lt_tag_convert_from_locale_string ()
void | lt_tag_dump ()
lt_bool_t | lt_tag_compare ()
lt_bool_t | lt_tag_match ()
char * | lt_tag_lookup ()
char * | lt_tag_transform ()
const lt_lang_t * | lt_tag_get_language ()
const lt_extlang_t * | lt_tag_get_extlang ()
const lt_script_t * | lt_tag_get_script ()
const lt_region_t * | lt_tag_get_region ()
const lt_list_t * | lt_tag_get_variants ()
const lt_extension_t * | lt_tag_get_extension ()
const lt_string_t * | lt_tag_get_privateuse ()
const lt_grandfathered_t * | lt_tag_get_grandfathered ()

## Types and Values

enum | lt_tag_filter_t
| lt_tag_t

## Description

This container class provides an interface to deal with the language tag.

## Functions

### lt_tag_new ()

    lt_tag_t *
    lt_tag_new (void);

Create a new instance of lt_tag_t.

#### Returns

a new instance of lt_tag_t.

[transfer full]

### lt_tag_ref ()

    lt_tag_t *
    lt_tag_ref (lt_tag_t *tag);

Increases the reference count of `tag` .

#### Parameters

tag | a lt_tag_t. |

#### Returns

the same `tag` object.

[transfer none]

### lt_tag_unref ()

    void
    lt_tag_unref (lt_tag_t *tag);

Decreases the reference count of `tag` . when its reference count drops to 0, the object is finalized (i.e. its memory is freed).

#### Parameters

tag | a lt_tag_t. |

### lt_tag_parse ()

    lt_bool_t
    lt_tag_parse (lt_tag_t *tag,
                  const char *tag_string,
                  lt_error_t **error);

Parse `tag_string` and create appropriate instances for subtags.

#### Parameters

tag | a lt_tag_t. |
tag_string | language tag to be parsed. |
error | a lt_error_t or `NULL`. | [allow-none]

#### Returns

`TRUE` if it's successfully completed, otherwise `FALSE`.

### lt_tag_parse_with_extra_token ()

    lt_bool_t
    lt_tag_parse_with_extra_token (lt_tag_t *tag,
                                   const char *tag_string,
                                   lt_error_t **error);

Continue to parse a language tag with `tag_string` . please use `lt_tag_parse()` at first.

#### Parameters

tag | a lt_tag_t. |
tag_string | a language tag to be parsed much more. |
error | a lt_error_t or `NULL`. | [allow-none]

#### Returns

`TRUE` if it's successfully completed, otherwise `FALSE`.

### lt_tag_clear ()

    void
    lt_tag_clear (lt_tag_t *tag);

(Re-)Initialize all of the subtag information stored in `tag` .

#### Parameters

tag | a lt_tag_t. |

### lt_tag_copy ()

    lt_tag_t *
    lt_tag_copy (const lt_tag_t *tag);

Create a copy instance of `tag` .

#### Parameters

tag | a lt_tag_t. |

#### Returns

a new instance of lt_tag_t or `NULL` if fails.

[transfer full]

### lt_tag_truncate ()

    lt_bool_t
    lt_tag_truncate (lt_tag_t *tag,
                     lt_error_t **error);

Truncate the last subtag.

#### Parameters

tag | a lt_tag_t. |
error | a lt_error_t. | [allow-none]

#### Returns

`TRUE` if a subtag was truncated, otherwise `FALSE`.

### lt_tag_get_string_with_filter ()

    const char *
    lt_tag_get_string_with_filter (lt_tag_t *tag,
                                   int filter);

Obtains a language tag in string against `filter` .

#### Parameters

tag | a lt_tag_t. |
filter | a binary count sequence of lt_tag_filter_t. |

#### Returns

a language tag string.

### lt_tag_get_string ()

    const char *
    lt_tag_get_string (lt_tag_t *tag);

Obtains a language tag in string.

#### Parameters

tag | a lt_tag_t. |

#### Returns

a language tag string.

### lt_tag_canonicalize ()

    char *
    lt_tag_canonicalize (lt_tag_t *tag,
                         lt_error_t **error);

Canonicalize the language tag according to various information of subtags.

#### Parameters

tag | a lt_tag_t. |
error | a lt_error_t or `NULL`. | [allow-none]

#### Returns

a language tag string.

### lt_tag_canonicalize_in_extlang_form ()

    char *
    lt_tag_canonicalize_in_extlang_form (lt_tag_t *tag,
                                         lt_error_t **error);

Canonicalize the language tag in the extlang form according to various information of subtags.

#### Parameters

tag | a lt_tag_t. |
error | a lt_error_t or `NULL`. | [allow-none]

#### Returns

a language tag string.

### lt_tag_convert_to_locale ()

    char *
    lt_tag_convert_to_locale (lt_tag_t *tag,
                              lt_error_t **error);

Convert the language tag to the locale.

#### Parameters

tag | a lt_tag_t. |
error | a lt_error_t or `NULL`. | [allow-none]

#### Returns

a locale string or `NULL` if fails

### lt_tag_convert_from_locale ()

    lt_tag_t *
    lt_tag_convert_from_locale (lt_error_t **error);

Convert current locale to the language tag.

#### Parameters

error | a lt_error_t. | [allow-none]

#### Returns

a lt_tag_t, `NULL` if fails.

[transfer full]

### lt_tag_convert_from_locale_string ()

    lt_tag_t *
    lt_tag_convert_from_locale_string (const char *locale,
                                       lt_error_t **error);

Convert `locale` to the language tag.

#### Parameters

locale | a locale string |
error | a lt_error_t or `NULL`. | [allow-none]

#### Returns

a lt_tag_t, `NULL` if fails.

[transfer full]

### lt_tag_dump ()

    void
    lt_tag_dump (const lt_tag_t *tag);

Dumps the container information to the standard output.

#### Parameters

tag | a lt_tag_t. |

### lt_tag_compare ()

    lt_bool_t
    lt_tag_compare (const lt_tag_t *v1,
                    const lt_tag_t *v2);

Compare if `v1` and `v2` is the same object or not.

#### Parameters

v1 | a lt_tag_t. |
v2 | a lt_tag_t. |

#### Returns

`TRUE` if it's the same, otherwise `FALSE`.

### lt_tag_match ()

    lt_bool_t
    lt_tag_match (const lt_tag_t *v1,
                  const char *v2,
                  lt_error_t **error);

Try matching of `v1` and `v2` . any of subtags in `v2` is allowed to use the wildcard according to the syntax in RFC 4647.

#### Parameters

v1 | a lt_tag_t. |
v2 | a language range string. |
error | a lt_error_t or `NULL`. | [allow-none]

#### Returns

`TRUE` if it matches, otherwise `FALSE`.

### lt_tag_lookup ()

    char *
    lt_tag_lookup (const lt_tag_t *tag,
                   const char *pattern,
                   lt_error_t **error);

Lookup the language tag that `tag` meets with `pattern` . Any of subtags in `pattern` is allowed to use the wildcard according to the syntax in RFC 4647.

#### Parameters

tag | a lt_tag_t. |
pattern | a language range string. |
error | a lt_error_t or `NULL`. | [allow-none]

#### Returns

a language tag string if any matches, otherwise `NULL`.

### lt_tag_transform ()

    char *
    lt_tag_transform (lt_tag_t *tag,
                      lt_error_t **error);

Transform `tag` according to the likelySubtags database provided by CLDR.

#### Parameters

tag | a lt_tag_t. |
error | a lt_error_t or `NULL`. | [allow-none]

#### Returns

a string.

### lt_tag_get_language ()

    const lt_lang_t *
    lt_tag_get_language (const lt_tag_t *tag);

Obtain a lt_lang_t instance in `tag` .

#### Parameters

tag | a lt_tag_t. |

#### Returns

a lt_lang_t.

[transfer none]

### lt_tag_get_extlang ()

    const lt_extlang_t *
    lt_tag_get_extlang (const lt_tag_t *tag);

Obtain a lt_extlang_t instance in `tag` .

#### Parameters

tag | a lt_tag_t. |

#### Returns

a lt_extlang_t.

[transfer none]

### lt_tag_get_script ()

    const lt_script_t *
    lt_tag_get_script (const lt_tag_t *tag);

Obtain a lt_script_t instance in `tag` .

#### Parameters

tag | a lt_tag_t. |

#### Returns

a lt_script_t.

[transfer none]

### lt_tag_get_region ()

    const lt_region_t *
    lt_tag_get_region (const lt_tag_t *tag);

Obtain a lt_region_t instance in `tag` .

#### Parameters

tag | a lt_tag_t. |

#### Returns

a lt_region_t.

[transfer none]

### lt_tag_get_variants ()

    const lt_list_t *
    lt_tag_get_variants (const lt_tag_t *tag);

Obtain a list of lt_variant_t instance in `tag` .

#### Parameters

tag | a lt_tag_t. |

#### Returns

a lt_list_t containing lt_variant_t.

[transfer none]

### lt_tag_get_extension ()

    const lt_extension_t *
    lt_tag_get_extension (const lt_tag_t *tag);

Obtain a lt_extension_t instance in `tag` .

#### Parameters

tag | a lt_tag_t. |

#### Returns

a lt_extension_t.

[transfer none]

### lt_tag_get_privateuse ()

    const lt_string_t *
    lt_tag_get_privateuse (const lt_tag_t *tag);

Obtain a lt_string_t instance in `tag` .

#### Parameters

tag | a lt_tag_t. |

#### Returns

a lt_string_t.

[transfer none]

### lt_tag_get_grandfathered ()

    const lt_grandfathered_t *
    lt_tag_get_grandfathered (const lt_tag_t *tag);

Obtain a lt_grandfathered_t instance in `tag` .

#### Parameters

tag | a lt_tag_t. |

#### Returns

a lt_grandfathered_t.

[transfer none]

## Types and Values

### enum lt_tag_filter_t

This is used as a binary count sequence with `lt_tag_get_string_with_filter()` to allow only given tags to be the outcome.

#### Members

LT_TAG_FILTER_NONE | all of objects filtered. |
LT_TAG_FILTER_LANGUAGE | include lt_lang_t object into the result. |
LT_TAG_FILTER_EXTLANG | include lt_extlang_t object into the result. |
LT_TAG_FILTER_SCRIPT | include lt_script_t object into the result. |
LT_TAG_FILTER_REGION | include lt_region_t object into the result. |
LT_TAG_FILTER_VARIANT | include lt_variant_t object into the result. |
LT_TAG_FILTER_EXTENSION | include lt_extension_t object into the result. |
LT_TAG_FILTER_PRIVATEUSE | include the privateuse object into the result. |
LT_TAG_FILTER_GRANDFATHERED | include lt_grandfathered_t object into the result. |
LT_TAG_FILTER_ALL | no objects filtered. |

### lt_tag_t

    typedef struct _lt_tag_t lt_tag_t;

All the fields in the lt_tag_t structure are private to the lt_tag_t implementation.