src/include/mobile/utils_i18n_usearch.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  *    Licensed under the Apache License, Version 2.0 (the "License");
   5  *    you may not use this file except in compliance with the License.
   6  *    You may obtain a copy of the License at
   7  *
   8  *        http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  *    Unless required by applicable law or agreed to in writing, software
  11  *    distributed under the License is distributed on an "AS IS" BASIS,
  12  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  *    See the License for the specific language governing permissions and
  14  *    limitations under the License.
  15  */
  16
  17 #ifndef __UTILS_I18N_USEARCH_H__
  18 #define __UTILS_I18N_USEARCH_H__
  19
  20 #include <utils_i18n_types.h>
  21
  22 /**
  23  * @file utils_i18n_usearch.h
  24  * @version 0.1
  25  * @brief utils_i18n_usearch
  26  */
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /**
  33  * @ingroup CAPI_BASE_UTILS_I18N_MODULE
  34  * @defgroup CAPI_BASE_UTILS_I18N_USEARCH_MODULE Usearch
  35  * @brief The Usearch module provides language-sensitive text searching based on the comparison rules defined in a ucollator data struct.
  36  *
  37  * @section CAPI_BASE_UTILS_I18N_USEARCH_MODULE_HEADER Required Header
  38  *  \#include <utils_i18n.h>
  39  *
  40  * @section CAPI_BASE_UTILS_I18N_USEARCH_MODULE_OVERVIEW Overview
  41  * @details The Usearch module provides language-sensitive text searching based on the comparison rules defined in a ucollator data struct.
  42  *
  43  * @section CAPI_BASE_UTILS_I18N_USEARCH_MODULE_SAMPLE_CODE_1 Sample Code 1
  44  * @brief Searches the pattern and gets the matched text.
  45  * @code
  46     char *string = "TIZEN";
  47     char *keyword = "ZE";
  48     i18n_uchar target[16] = {0,};
  49     i18n_uchar pattern[16] = {0,};
  50     i18n_uchar u_matched[16] = {0,};
  51     char tmp[1] = {0};
  52     i18n_usearch_h search = NULL;
  53     int pos = 0;
  54     int matched_text_len = 0;
  55     int i = 0;
  56     i18n_error_code_e error_code;
  57
  58     i18n_ustring_from_UTF8( target, 16, NULL, string, -1, &error_code );
  59     i18n_ustring_from_UTF8( pattern, 16, NULL, keyword, -1, &error_code );
  60
  61     // creates a search
  62     i18n_usearch_create_new( pattern, -1, target, -1, "en_US", NULL, &search );
  63
  64     // gets the first index of the target that matches with the pattern
  65     i18n_usearch_first( search, &pos );
  66     dlog_print(DLOG_INFO, LOG_TAG, "the first index = %d", pos );    // The first index = 2
  67
  68     // gets the matched text
  69     i18n_usearch_get_matched_text( search, u_matched, 16, &matched_text_len );
  70     for ( i = 0; i < matched_text_len; i++) {
  71         i18n_ustring_copy_au_n( tmp, &u_matched[i], 1 );
  72         dlog_print(DLOG_INFO, LOG_TAG, "u_matched[%d] = %c", i, tmp[0] );    // u_matched[0] = Z, u_matched[1] = E
  73     }
  74     i18n_usearch_destroy( search );
  75  * @endcode
  76  */
  77
  78 /**
  79  * @addtogroup CAPI_BASE_UTILS_I18N_USEARCH_MODULE
  80  * @{
  81  */
  82
  83 /**
  84  * @brief Creates an i18n_usearch_h using the argument locale language rule set.
  85  * @details A collator will be created in the process, which will be owned by
  86  * this search and will be deleted in i18n_usearch_destroy().
  87  * @remarks Must release @a search_iter using i18n_usearch_destroy().
  88  * @since_tizen 2.3
  89  *
  90  * @deprecated Deprecated since 2.3.1. Use i18n_usearch_create_new() instead.
  91  *
  92  * @param[in] pattern The pattern for matching
  93  * @param[in] pattern_len The length of the pattern, otherwise @c -1 for NULL-termination
  94  * @param[in] text The text string
  95  * @param[in] text_len The length of the text string, otherwise @c -1 for NULL-termination
  96  * @param[in] locale The name of the locale for the rules to be used
  97  * @param[in] break_iter An #i18n_ubreak_iterator_s that will be used to restrict the points at which matches are detected. If a match is found,\n
  98  * but the match's start or end index is not a boundary as determined by the #i18n_ubreak_iterator_s,
  99  * the match will be rejected and another will be searched for. If this parameter is @c NULL,\n
 100  * no break detection is attempted.
 101  * @param[out] search_iter The #i18n_usearch_h, otherwise @c NULL if there is an error
 102  *
 103  * @retval #I18N_ERROR_NONE Successful
 104  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 105  */
 106 int i18n_usearch_create ( const i18n_uchar *pattern, int32_t pattern_len, const i18n_uchar *text, int32_t text_len, const char *locale, i18n_ubreak_iterator_s *break_iter, i18n_usearch_h *search_iter );
 107
 108 /**
 109  * @brief Creates an #i18n_usearch_h using the argument locale language rule set.
 110  * @details A collator will be created in the process, which will be owned by
 111  * this search and will be deleted in i18n_usearch_destroy().
 112  * @remarks Must release @a search_iter using i18n_usearch_destroy().
 113  * @since_tizen 2.3.1
 114  *
 115  * @param[in] pattern The pattern for matching
 116  * @param[in] pattern_len The length of the pattern, otherwise @c -1 for NULL-termination
 117  * @param[in] text The text string
 118  * @param[in] text_len The length of the text string, otherwise @c -1 for NULL-termination
 119  * @param[in] locale The name of the locale for the rules to be used
 120  * @param[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,\n
 121  * but the match's start or end index is not a boundary as determined by the #i18n_ubreak_iterator_h,
 122  * the match will be rejected and another will be searched for. If this parameter is @c NULL,\n
 123  * no break detection is attempted.
 124  * @param[out] search_iter The #i18n_usearch_h, otherwise @c NULL if there is an error
 125  *
 126  * @retval #I18N_ERROR_NONE Successful
 127  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 128  */
 129 int i18n_usearch_create_new ( const i18n_uchar *pattern, int32_t pattern_len, const i18n_uchar *text,
 130         int32_t text_len, const char *locale, i18n_ubreak_iterator_h break_iter, i18n_usearch_h *search_iter);
 131
 132 /**
 133  * @brief Destroys and cleans up the i18n_usearch_h.
 134  * @details If a collator is created in i18n_usearch_create(), it will be destroyed here.
 135  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 136  *
 137  * @param[in] search_iter The i18n_usearch_h to clean up
 138  *
 139  * @retval #I18N_ERROR_NONE Successful
 140  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 141  */
 142 int i18n_usearch_destroy ( i18n_usearch_h search_iter );
 143
 144 /**
 145  * @brief Returns the text that matches by the most recent call to i18n_usearch_first(), or so on.
 146  * @details If the iterator is not pointing at a valid match (e.g. just after
 147  * construction or after #I18N_USEARCH_DONE has been returned, it returns
 148  * an empty string. If the result is not large enough to store the matched text,
 149  * the result will be filled with the partial text and an #I18N_ERROR_BUFFER_OVERFLOW
 150  * will be returned in status. The result will be NULL-terminated whenever
 151  * possible. If the buffer fits the matched text exactly, a NULL-termination
 152  * is not possible.
 153  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 154  *
 155  * @param[in]  search_iter The search iterator handle
 156  * @param[out] result i18n_uchar The buffer to store the matched string
 157  * @param[in]  result_capacity The length of the result buffer
 158  * @param[out] len_matched_text The exact length of the matched text, not counting the NULL-termination
 159  *
 160  * @retval #I18N_ERROR_NONE Successful
 161  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 162  * @retval #I18N_ERROR_BUFFER_OVERFLOW A result would not fit in the supplied buffer
 163  */
 164 int i18n_usearch_get_matched_text ( const i18n_usearch_h search_iter, i18n_uchar *result, int32_t result_capacity, int32_t *len_matched_text );
 165
 166 /**
 167  * @brief Gets the collator used for the language rules.
 168  * @details Deleting the returned i18n_ucollator_h before calling
 169  * i18n_usearch_destroy() would cause the string search to fail.
 170  * i18n_usearch_destroy() will delete the collator if this search owns it.
 171  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 172  *
 173  * @param[in] search_iter The search iterator handle
 174  * @param[out] collator The collator
 175  *
 176  * @retval #I18N_ERROR_NONE Successful
 177  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 178  */
 179 int i18n_usearch_get_collator ( const i18n_usearch_h search_iter, i18n_ucollator_h *collator );
 180
 181 /**
 182  * @brief Returns the first index at which the string text matches the search pattern.
 183  * @details The iterator is adjusted so that its current index
 184  * is the match position if one is found.
 185  * If a match is not found, #I18N_USEARCH_DONE will be returned and
 186  * the iterator will be adjusted to the index #I18N_USEARCH_DONE.
 187  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 188  *
 189  * @param[in] search_iter The search iterator handle
 190  * @param[out] index_first The character index of the first match,
 191  * otherwise #I18N_USEARCH_DONE if there are no matches.
 192  *
 193  * @retval #I18N_ERROR_NONE Successful
 194  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 195  */
 196 int i18n_usearch_first ( i18n_usearch_h search_iter, int32_t *index_first );
 197
 198 #ifdef __cplusplus
 199 }
 200 #endif
 201
 202 /**
 203  * @}
 204  * @}
 205  */
 206
 207 #endif  /* __UTILS_I18N_USEARCH_H__*/