Top |
Functions
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 () |
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_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] |
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 |
[allow-none][out][transfer full] |
error |
A location to store a GError from the E_COLLATOR_ERROR domain. |
[allow-none] |
Since: 3.12
e_collator_ref ()
ECollator *
e_collator_ref (ECollator *collator
);
Increases the reference count of collator
.
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
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] |
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'.
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 |
[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] |
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 |
[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.
Since: 3.12
Types and Values
E_COLLATOR_ERROR
#define E_COLLATOR_ERROR (e_collator_error_quark ())
An error domain for collation errors
Since: 3.12
enum ECollatorError
Errors from the E_COLLATOR_ERROR domain.
Members
An error occured trying to open a collator and access collation data. |
||
An error occurred converting character encodings |
||
A malformed locale name was given to |
ECollator
typedef struct _ECollator ECollator;
An opaque object used for locale specific string comparisons and sort ordering.
Since: 3.12