## TranslatePair

TranslatePair — language pair object and functions for handling pair lists

## Synopsis

    struct      TranslatePair;
    enum        TranslatePairFlags;
    TranslatePair* translate_pair_new           (TranslatePairFlags flags,
                                                 const char *from,
                                                 const char *to);
    TranslatePairFlags translate_pair_get_flags (TranslatePair *pair);
    const char* translate_pair_get_from         (TranslatePair *pair);
    const char* translate_pair_get_to           (TranslatePair *pair);
    GSList*     translate_pairs_sort_by_tag     (GSList *pairs);
    GSList*     translate_pairs_sort_by_name    (GSList *pairs);
    TranslatePair* translate_pairs_find         (const GSList *pairs,
                                                 const char *from,
                                                 const char *to);

## Object Hierarchy

      GObject
       +----TranslatePair

## Properties

      "flags"                TranslatePairFlags   : Read / Write / Construct Only
      "from"                 gchararray           : Read / Write / Construct Only
      "to"                   gchararray           : Read / Write / Construct Only

## Description

A TranslatePair object defines the source and destination languages of a translation, as well as flags specifying the contexts of application of the pair.

You only need to create pairs if you are implementing a service (see the `get_pairs` method of TranslateServiceClass).

## Details

### struct TranslatePair

    struct TranslatePair;

The TranslatePair struct contains private data only, and should be accessed using the functions below.

### enum TranslatePairFlags

    typedef enum
    {
      TRANSLATE_PAIR_TEXT		= 1 << 0,
      TRANSLATE_PAIR_WEB_PAGE	= 1 << 1
    } TranslatePairFlags;

Specifies the features of a TranslatePair object.

`TRANSLATE_PAIR_TEXT` | the pair can be used to translate text
`TRANSLATE_PAIR_WEB_PAGE` | the pair can be used to translate a web page

### translate_pair_new ()

    TranslatePair* translate_pair_new           (TranslatePairFlags flags,
                                                 const char *from,
                                                 const char *to);

Creates a new language pair.

`flags` : | the pair flags.
`from` : | the source language RFC 3066 tag.
`to` : | the destination language RFC 3066 tag.
Returns : | a new language pair.

### translate_pair_get_flags ()

    TranslatePairFlags translate_pair_get_flags (TranslatePair *pair);

Gets the flags of `pair`.

`pair` : | a pair.
Returns : | the pair flags.

### translate_pair_get_from ()

    const char* translate_pair_get_from         (TranslatePair *pair);

Gets the source language of `pair`.

`pair` : | a pair.
Returns : | the RFC 3066 tag of the source language of `pair`.

### translate_pair_get_to ()

    const char* translate_pair_get_to           (TranslatePair *pair);

Gets the destination language of `pair`.

`pair` : | a pair.
Returns : | the RFC 3066 tag of the destination language of `pair`.

### translate_pairs_sort_by_tag ()

    GSList*     translate_pairs_sort_by_tag     (GSList *pairs);

Sorts a pair list by source and destination RFC 3066 tag. Tag comparisons are performed using `translate_ascii_strcasecoll()`.

`pairs` : | a list of TranslatePair objects.
Returns : | `pairs` sorted.

### translate_pairs_sort_by_name ()

    GSList*     translate_pairs_sort_by_name    (GSList *pairs);

Sorts a pair list by source and destination human-readable language name. Names are obtained using `translate_get_language_name()`, and are compared using `translate_utf8_strcasecoll()`.

`pairs` : | a list of TranslatePair objects.
Returns : | `pairs` sorted.

### translate_pairs_find ()

    TranslatePair* translate_pairs_find         (const GSList *pairs,
                                                 const char *from,
                                                 const char *to);

Finds the first pair in `pairs` whose source and/or destination language match `from` and/or `to`.

`pairs` : | a list of TranslatePair objects.
`from` : | a RFC 3066 tag, or `NULL`.
`to` : | a RFC 3066 tag, or `NULL`.
Returns : | a pair, or `NULL` if not found. The returned pair belongs to `pairs`, its reference count is not incremented.

## Properties

"`flags`" (TranslatePairFlags : Read / Write / Construct Only) | The pair flags.
"`from`" (gchararray : Read / Write / Construct Only) | The source language RFC 3066 tag.
"`to`" (gchararray : Read / Write / Construct Only) | The destination language RFC 3066 tag.