The Usearch module provides language-sensitive text searching based on the comparison rules defined in a ucollator data struct.

Required Header

#include <utils_i18n.h>

Overview

The Usearch module provides language-sensitive text searching based on the comparison rules defined in a ucollator data struct.

Sample Code 1

Searches the pattern and gets the matched text.

    char *string = "TIZEN";
    char *keyword = "ZE";
    i18n_uchar target[16] = {0,};
    i18n_uchar pattern[16] = {0,};
    i18n_uchar u_matched[16] = {0,};
    char tmp[1] = {0};
    i18n_usearch_h search = NULL;
    int pos = 0;
    int matched_text_len = 0;
    int i = 0;
    i18n_error_code_e error_code;

    i18n_ustring_from_UTF8( target, 16, NULL, string, -1, &error_code );
    i18n_ustring_from_UTF8( pattern, 16, NULL, keyword, -1, &error_code );

    // creates a search
    i18n_usearch_create_new( pattern, -1, target, -1, "en_US", NULL, &search );

    // gets the first index of the target that matches with the pattern
    i18n_usearch_first( search, &pos );
    dlog_print(DLOG_INFO, LOG_TAG, "the first index = %d", pos );    // The first index = 2

    // gets the matched text
    i18n_usearch_get_matched_text( search, u_matched, 16, &matched_text_len );
    for ( i = 0; i < matched_text_len; i++) {
        i18n_ustring_copy_au_n( tmp, &u_matched[i], 1 );
        dlog_print(DLOG_INFO, LOG_TAG, "u_matched[%d] = %c", i, tmp[0] );    // u_matched[0] = Z, u_matched[1] = E
    }
    i18n_usearch_destroy( search );

Functions
int	i18n_usearch_create_new (const i18n_uchar pattern, int32_t pattern_len, const i18n_uchar text, int32_t text_len, const char locale, i18n_ubreak_iterator_h break_iter, i18n_usearch_h search_iter)
	Creates an i18n_usearch_h using the argument locale language rule set.
int	i18n_usearch_destroy (i18n_usearch_h search_iter)
	Destroys and cleans up the i18n_usearch_h.
int	i18n_usearch_get_matched_text (const i18n_usearch_h search_iter, i18n_uchar result, int32_t result_capacity, int32_t len_matched_text)
	Returns the text that matches by the most recent call to i18n_usearch_first(), or so on.
int	i18n_usearch_get_collator (const i18n_usearch_h search_iter, i18n_ucollator_h *collator)
	Gets the collator used for the language rules.
int	i18n_usearch_first (i18n_usearch_h search_iter, int32_t *index_first)
	Returns the first index at which the string text matches the search pattern.
Typedefs
typedef void *	i18n_usearch_h
	i18n_usearch_h.

Typedef Documentation

typedef void* i18n_usearch_h

i18n_usearch_h.

Since :: 2.3

Function Documentation

int i18n_usearch_create_new	(	const i18n_uchar *	pattern,
		int32_t	pattern_len,
		const i18n_uchar *	text,
		int32_t	text_len,
		const char *	locale,
		i18n_ubreak_iterator_h	break_iter,
		i18n_usearch_h *	search_iter
	)

Creates an i18n_usearch_h using the argument locale language rule set.

A collator will be created in the process, which will be owned by this search and will be deleted in i18n_usearch_destroy().

Remarks:: Must release search_iter using i18n_usearch_destroy().

Since :: 2.3.1

Parameters:

[in]	pattern	The pattern for matching
[in]	pattern_len	The length of the pattern, otherwise `-1` for NULL-termination
[in]	text	The text string
[in]	text_len	The length of the text string, otherwise `-1` for NULL-termination
[in]	locale	The name of the locale for the rules to be used
[in]	break_iter	An i18n_ubreak_iterator_h that will be used to restrict the points at which matches are detected. If a match is found, but the match's start or end index is not a boundary as determined by the i18n_ubreak_iterator_h, the match will be rejected and another will be searched for. If this parameter is `NULL`, no break detection is attempted.
[out]	search_iter	The i18n_usearch_h, otherwise `NULL` if there is an error

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_usearch_destroy ( i18n_usearch_h search_iter )

Destroys and cleans up the i18n_usearch_h.

If a collator is created in i18n_usearch_create_new(), it will be destroyed here.

Since :: 2.3

Parameters:

[in] search_iter The i18n_usearch_h to clean up

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_usearch_first	(	i18n_usearch_h	search_iter,
		int32_t *	index_first
	)

Returns the first index at which the string text matches the search pattern.

The iterator is adjusted so that its current index is the match position if one is found. If a match is not found, I18N_USEARCH_DONE will be returned and the iterator will be adjusted to the index I18N_USEARCH_DONE.

Since :: 2.3

Parameters:

[in]	search_iter	The search iterator handle
[out]	index_first	The character index of the first match, otherwise I18N_USEARCH_DONE if there are no matches.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_usearch_get_collator	(	const i18n_usearch_h	search_iter,
		i18n_ucollator_h *	collator
	)

Gets the collator used for the language rules.

Deleting the returned i18n_ucollator_h before calling i18n_usearch_destroy() would cause the string search to fail. i18n_usearch_destroy() will delete the collator if this search owns it.

Since :: 2.3

Parameters:

[in]	search_iter	The search iterator handle
[out]	collator	The collator

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_usearch_get_matched_text	(	const i18n_usearch_h	search_iter,
		i18n_uchar *	result,
		int32_t	result_capacity,
		int32_t *	len_matched_text
	)

Returns the text that matches by the most recent call to i18n_usearch_first(), or so on.

If the iterator is not pointing at a valid match (e.g. just after construction or after I18N_USEARCH_DONE has been returned, it returns an empty string. If the result is not large enough to store the matched text, the result will be filled with the partial text and an I18N_ERROR_BUFFER_OVERFLOW will be returned in status. The result will be NULL-terminated whenever possible. If the buffer fits the matched text exactly, a NULL-termination is not possible.

Since :: 2.3

Parameters:

[in]	search_iter	The search iterator handle
[out]	result	i18n_uchar The buffer to store the matched string
[in]	result_capacity	The length of the result buffer
[out]	len_matched_text	The exact length of the matched text, not counting the NULL-termination

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_BUFFER_OVERFLOW	A result would not fit in the supplied buffer

Required Header

Overview

Sample Code 1

Functions

Typedefs

Typedef Documentation

Function Documentation