src/include/wearable/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.1
  89  *
  90  * @param[in] pattern The pattern for matching
  91  * @param[in] pattern_len The length of the pattern, otherwise @c -1 for NULL-termination
  92  * @param[in] text The text string
  93  * @param[in] text_len The length of the text string, otherwise @c -1 for NULL-termination
  94  * @param[in] locale The name of the locale for the rules to be used
  95  * @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
  96  * but the match's start or end index is not a boundary as determined by the #i18n_ubreak_iterator_h,
  97  * the match will be rejected and another will be searched for. If this parameter is @c NULL,\n
  98  * no break detection is attempted.
  99  * @param[out] search_iter The #i18n_usearch_h, otherwise @c NULL if there is an error
 100  *
 101  * @retval #I18N_ERROR_NONE Successful
 102  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 103  */
 104 int i18n_usearch_create_new ( const i18n_uchar *pattern, int32_t pattern_len, const i18n_uchar *text,
 105         int32_t text_len, const char *locale, i18n_ubreak_iterator_h break_iter, i18n_usearch_h *search_iter);
 106
 107 /**
 108  * @brief Destroys and cleans up the i18n_usearch_h.
 109  * @details If a collator is created in i18n_usearch_create_new(), it will be destroyed here.
 110  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 111  *
 112  * @param[in] search_iter The i18n_usearch_h to clean up
 113  *
 114  * @retval #I18N_ERROR_NONE Successful
 115  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 116  */
 117 int i18n_usearch_destroy ( i18n_usearch_h search_iter );
 118
 119 /**
 120  * @brief Returns the text that matches by the most recent call to i18n_usearch_first(), or so on.
 121  * @details If the iterator is not pointing at a valid match (e.g. just after
 122  * construction or after #I18N_USEARCH_DONE has been returned, it returns
 123  * an empty string. If the result is not large enough to store the matched text,
 124  * the result will be filled with the partial text and an #I18N_ERROR_BUFFER_OVERFLOW
 125  * will be returned in status. The result will be NULL-terminated whenever
 126  * possible. If the buffer fits the matched text exactly, a NULL-termination
 127  * is not possible.
 128  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 129  *
 130  * @param[in]  search_iter The search iterator handle
 131  * @param[out] result i18n_uchar The buffer to store the matched string
 132  * @param[in]  result_capacity The length of the result buffer
 133  * @param[out] len_matched_text The exact length of the matched text, not counting the NULL-termination
 134  *
 135  * @retval #I18N_ERROR_NONE Successful
 136  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 137  * @retval #I18N_ERROR_BUFFER_OVERFLOW A result would not fit in the supplied buffer
 138  */
 139 int i18n_usearch_get_matched_text ( const i18n_usearch_h search_iter, i18n_uchar *result, int32_t result_capacity, int32_t *len_matched_text );
 140
 141 /**
 142  * @brief Gets the collator used for the language rules.
 143  * @details Deleting the returned i18n_ucollator_h before calling
 144  * i18n_usearch_destroy() would cause the string search to fail.
 145  * i18n_usearch_destroy() will delete the collator if this search owns it.
 146  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 147  *
 148  * @param[in] search_iter The search iterator handle
 149  * @param[out] collator The collator
 150  *
 151  * @retval #I18N_ERROR_NONE Successful
 152  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 153  */
 154 int i18n_usearch_get_collator ( const i18n_usearch_h search_iter, i18n_ucollator_h *collator );
 155
 156 /**
 157  * @brief Returns the first index at which the string text matches the search pattern.
 158  * @details The iterator is adjusted so that its current index
 159  * is the match position if one is found.
 160  * If a match is not found, #I18N_USEARCH_DONE will be returned and
 161  * the iterator will be adjusted to the index #I18N_USEARCH_DONE.
 162  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 163  *
 164  * @param[in] search_iter The search iterator handle
 165  * @param[out] index_first The character index of the first match,
 166  * otherwise #I18N_USEARCH_DONE if there are no matches.
 167  *
 168  * @retval #I18N_ERROR_NONE Successful
 169  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 170  */
 171 int i18n_usearch_first ( i18n_usearch_h search_iter, int32_t *index_first );
 172
 173 #ifdef __cplusplus
 174 }
 175 #endif
 176
 177 /**
 178  * @}
 179  * @}
 180  */
 181
 182 #endif  /* __UTILS_I18N_USEARCH_H__*/