Immutable Index

---

Immutable, thread-safe version of Alphabetic Index.

Required Header

#include <utils_i18n.h>

Overview

This module provides thread-safe methods for bucketing, and random access to buckets and their properties, but does not offer adding records to the index.

Functions
int	i18n_immutable_idx_create (i18n_alpha_idx_h index, i18n_immutable_idx_h *immutable_index)
	Creates an immutable index object.
int	i18n_immutable_idx_destroy (i18n_immutable_idx_h index)
	Destroys the immutable index object.
int	i18n_immutable_idx_get_bucket_count (i18n_immutable_idx_h index, int32_t *count)
	Returns the number of index buckets and labels, including underflow/inflow/overflow.
int	i18n_immutable_idx_get_bucket_index (i18n_immutable_idx_h index, char *name, int32_t *number)
	Finds the index bucket for the given name and returns the number of that bucket.
int	i18n_immutable_idx_get_bucket_label (i18n_immutable_idx_h index, int32_t bucket_index, char **label)
	Returns the label string of the index-th bucket.
int	i18n_immutable_idx_get_bucket_label_type (i18n_immutable_idx_h index, int32_t bucket_index, i18n_alpha_idx_label_type_e *type)
	Returns the label type of the index-th bucket.
Typedefs
typedef void *	i18n_immutable_idx_h
	An i18n_immutable_idx_h handle.

---

Typedef Documentation

typedef void* i18n_immutable_idx_h

An i18n_immutable_idx_h handle.

Use i18n_immutable_idx_* functions to operate on i18n_immutable_idx_h objects.

Since :

5.0

---

Function Documentation

int i18n_immutable_idx_create	(	i18n_alpha_idx_h	index,
		i18n_immutable_idx_h *	immutable_index
	)

Creates an immutable index object.

Since :

5.0

Remarks:

The created object should be released by the caller with the i18n_immutable_idx_destroy() function.

Parameters:

[in]	index	The alphabetic index the thread-safe version of which is to be created
[out]	immutable_index	The created immutable index object

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_immutable_idx_destroy

(

i18n_immutable_idx_h

index

)

Destroys the immutable index object.

Since :

5.0

Parameters:

[in]

index

The immutable index to be destroyed

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_immutable_idx_get_bucket_count	(	i18n_immutable_idx_h	index,
		int32_t *	count
	)

Returns the number of index buckets and labels, including underflow/inflow/overflow.

Since :

5.0

Parameters:

[in]	index	The immutable index object
[out]	count	The number of index buckets

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_immutable_idx_get_bucket_index	(	i18n_immutable_idx_h	index,
		char *	name,
		int32_t *	number
	)

Finds the index bucket for the given name and returns the number of that bucket.

Use i18n_immutable_idx_get_bucket_label() or i18n_immutable_idx_get_bucket_label_type() to get bucket properties.

Since :

5.0

Parameters:

[in]	index	The immutable index object
[in]	name	The string to be sorted into an index bucket
[out]	number	The bucket number for the name

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_immutable_idx_get_bucket_label	(	i18n_immutable_idx_h	index,
		int32_t	bucket_index,
		char **	label
	)

Returns the label string of the index-th bucket.

Since :

5.0

Remarks:

The returned string should be freed by the caller with free() function.

Parameters:

[in]	index	The immutable index object
[in]	bucket_index	The bucket number
[out]	label	The label string for the bucket

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_INDEX_OUTOFBOUNDS	Desired position is out of bounds

int i18n_immutable_idx_get_bucket_label_type	(	i18n_immutable_idx_h	index,
		int32_t	bucket_index,
		i18n_alpha_idx_label_type_e *	type
	)

Returns the label type of the index-th bucket.

Since :

5.0

Parameters:

[in]	index	The immutable index object
[in]	bucket_index	The bucket number
[out]	type	The alphabetic index label type

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_INDEX_OUTOFBOUNDS	Desired position is out of bounds