Tizen Native API
Usearch

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]patternThe pattern for matching
[in]pattern_lenThe length of the pattern, otherwise -1 for NULL-termination
[in]textThe text string
[in]text_lenThe length of the text string, otherwise -1 for NULL-termination
[in]localeThe name of the locale for the rules to be used
[in]break_iterAn 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_iterThe i18n_usearch_h, otherwise NULL if there is an error
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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_iterThe i18n_usearch_h to clean up
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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_iterThe search iterator handle
[out]index_firstThe character index of the first match, otherwise I18N_USEARCH_DONE if there are no matches.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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_iterThe search iterator handle
[out]collatorThe collator
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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_iterThe search iterator handle
[out]resulti18n_uchar The buffer to store the matched string
[in]result_capacityThe length of the result buffer
[out]len_matched_textThe exact length of the matched text, not counting the NULL-termination
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWA result would not fit in the supplied buffer