## ECollator

ECollator — Collation services for locale sensitive sorting

## Functions

#define | E_COLLATOR_ERROR
GQuark | e_collator_error_quark ()
ECollator * | e_collator_new ()
ECollator * | e_collator_new_interpret_country ()
ECollator * | e_collator_ref ()
void | e_collator_unref ()
gchar * | e_collator_generate_key ()
gchar * | e_collator_generate_key_for_index ()
gboolean | e_collator_collate ()
const gchar *const * | e_collator_get_index_labels ()
gint | e_collator_get_index ()

## Types and Values

enum | ECollatorError
| ECollator

## Includes

    #include <libedataserver/libedataserver.h>

## Description

The ECollator is a wrapper object around ICU collation services and provides features to sort words in locale specific ways. The collator also provides some API for determining features of the active alphabet in the user's locale, and which words should be sorted under which letter in the user's alphabet.

## Functions

### E_COLLATOR_ERROR

    #define E_COLLATOR_ERROR (e_collator_error_quark ())

An error domain for collation errors

Since 3.12

### e_collator_error_quark ()

    GQuark
    e_collator_error_quark (void);

### e_collator_new ()

    ECollator *
    e_collator_new (const gchar *locale,
                    GError **error);

Creates a new ECollator for the given `locale` , the returned collator should be freed with `e_collator_unref()`.

#### Parameters

locale | The locale under which to sort |
error | A location to store a GError from the E_COLLATOR_ERROR domain. | [allow-none]

#### Returns

A newly created ECollator.

[transfer full]

Since 3.12

### e_collator_new_interpret_country ()

    ECollator *
    e_collator_new_interpret_country (const gchar *locale,
                                      gchar **country_code,
                                      GError **error);

Creates a new ECollator for the given `locale` , the returned collator should be freed with `e_collator_unref()`.

In addition, this also reliably interprets the country code from the `locale` string and stores it to `country_code` .

#### Parameters

locale | The locale under which to sort |
country_code | A location to store the interpreted country code from `locale` . | [allow-none][out][transfer full]
error | A location to store a GError from the E_COLLATOR_ERROR domain. | [allow-none]

#### Returns

A newly created ECollator.

[transfer full]

Since 3.12

### e_collator_ref ()

    ECollator *
    e_collator_ref (ECollator *collator);

Increases the reference count of `collator` .

#### Parameters

collator | An ECollator |

#### Returns

`collator` .

[transfer full]

Since 3.12

### e_collator_unref ()

    void
    e_collator_unref (ECollator *collator);

Decreases the reference count of `collator` . If the reference count reaches 0 then the collator is freed

#### Parameters

collator | An ECollator |

Since 3.12

### e_collator_generate_key ()

    gchar *
    e_collator_generate_key (ECollator *collator,
                             const gchar *str,
                             GError **error);

Generates a collation key for `str` , the result of comparing two collation keys with `strcmp()` will be the same result of calling `e_collator_collate()` on the same original strings.

This function will first ensure that `str` is valid UTF-8 encoded.

#### Parameters

collator | An ECollator |
str | The string to generate a collation key for |
error | A location to store a GError from the E_COLLATOR_ERROR domain. | [allow-none]

#### Returns

A collation key for `str` , or `NULL` on failure with `error` set.

[transfer full]

Since 3.12

### e_collator_generate_key_for_index ()

    gchar *
    e_collator_generate_key_for_index (ECollator *collator,
                                       gint index);

Generates a sort key for the given alphabetic `index` .

The generated sort key is guaranteed to sort below any sort keys for words beginning with any variant of the given letter.

For instance, a sort key generated for the index 5 of a latin alphabet, where the fifth index is 'E' will sort below any sort keys generated for words starting with the characters 'e', 'E', 'é', 'É', 'è' or 'È'. It will also sort above any sort keys generated for words starting with the characters 'd' or 'D'.

#### Parameters

collator | An ECollator |
index | An index into the alphabetic labels |

#### Returns

A sort key for the given index.

[transfer full]

Since 3.12

### e_collator_collate ()

    gboolean
    e_collator_collate (ECollator *collator,
                        const gchar *str_a,
                        const gchar *str_b,
                        gint *result,
                        GError **error);

Compares `str_a` with `str_b` , the order of strings is determined by the parameters of `collator` .

The `result` will be set to integer less than, equal to, or greater than zero if `str_a` is found, respectively, to be less than, to match, or be greater than `str_b` .

Either `str_a` or `str_b` can be `NULL`, `NULL` strings are considered to sort below other strings.

This function will first ensure that both strings are valid UTF-8.

#### Parameters

collator | An ECollator |
str_a | A string to compare. | [allow-none]
str_b | The string to compare with `str_a` . | [allow-none]
result | A location to store the comparison result. | [out]
error | A location to store a GError from the E_COLLATOR_ERROR domain. | [allow-none]

#### Returns

`TRUE` on success, otherwise if `FALSE` is returned then `error` will be set.

Since 3.12

### e_collator_get_index_labels ()

    const gchar *const  *
    e_collator_get_index_labels (ECollator *collator,
                                 gint *n_labels,
                                 gint *underflow,
                                 gint *inflow,
                                 gint *overflow);

Fetches the displayable labels and index positions for the active alphabet.

#### Parameters

collator | An ECollator |
n_labels | The number of labels/indexes available for `collator` . | [out]
underflow | The underflow index, for any words which sort below the active alphabet(s). | [allow-none][out]
inflow | The inflow index, for any words which sort between the active alphabets (if there is more than one). | [allow-none][out]
overflow | The overflow index, for any words which sort above the active alphabet(s). | [allow-none][out]

#### Returns

The array of displayable labels for each index in the active alphabet(s).

[array zero-terminated=1][element-type utf8][transfer none]

Since 3.12

### e_collator_get_index ()

    gint
    e_collator_get_index (ECollator *collator,
                          const gchar *str);

Checks which index, as determined by `e_collator_get_index_labels()`, that `str` should sort under.

#### Parameters

collator | An ECollator |
str | A string |

#### Returns

The alphabetic index under which `str` would sort

Since 3.12

## Types and Values

### enum ECollatorError

Errors from the E_COLLATOR_ERROR domain.

#### Members

E_COLLATOR_ERROR_OPEN | An error occured trying to open a collator and access collation data. |
E_COLLATOR_ERROR_CONVERSION | An error occurred converting character encodings |
E_COLLATOR_ERROR_INVALID_LOCALE | A malformed locale name was given to `e_collator_new()` |

### ECollator

    typedef struct _ECollator ECollator;

An opaque object used for locale specific string comparisons and sort ordering.

Since 3.12