src/include/mobile/utils_i18n_unormalization.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_UNORMALIZATION_H__
  18 #define __UTILS_I18N_UNORMALIZATION_H__
  19
  20 #include <utils_i18n_types.h>
  21
  22 /**
  23  * @file utils_i18n_unormalization.h
  24  * @version 0.1
  25  * @brief utils_i18n_unormaliztion
  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_UNORMALIZATION_MODULE Unormalization
  35  * @brief The Unormalization module provides Unicode normalization functionality for standard unicode normalization.
  36  *
  37  * @section CAPI_BASE_UTILS_I18N_UNORMALIZATION_MODULE_HEADER Required Header
  38  *  \#include <utils_i18n.h>
  39  *
  40  * @section CAPI_BASE_UTILS_I18N_UNORMALIZATION_MODULE_OVERVIEW Overview
  41  * @details The Unormalization module provides Unicode normalization functionality for standard unicode normalization.
  42  * All instances of i18n_unormalizer_h are unmodifiable/immutable.
  43  * Instances returned by i18n_unormalization_get_instance() are singletons that must not be deleted by the caller.
  44  *
  45  * @section CAPI_BASE_UTILS_I18N_UNORMALIZATION_MODULE_SAMPLE_CODE_1 Sample Code 1
  46  * @brief Creates a normalizer and normalizes a unicode string
  47  * @code
  48     i18n_unormalizer_h normalizer = NULL;
  49     i18n_uchar src = 0xAC00;
  50     i18n_uchar dest[4] = {0,};
  51     int dest_str_len = 0;
  52     int i = 0;
  53
  54     // gets instance for normalizer
  55     i18n_unormalization_get_instance( NULL, "nfc", I18N_UNORMALIZATION_DECOMPOSE, &normalizer );
  56
  57     // normalizes a unicode string
  58     i18n_unormalization_normalize( normalizer, &src, 1, dest, 4, &dest_str_len );
  59     dlog_print(DLOG_INFO, LOG_TAG, "src is 0x%x\n", src );    // src is 0xAC00 (0xAC00: A Korean character combined with consonant and vowel)
  60
  61     for ( i = 0; i < dest_str_len; i++ ) {
  62         dlog_print(DLOG_INFO, LOG_TAG, "dest[%d] is 0x%x\t", i + 1, dest[i] );    // dest[1] is 0x1100  dest[2] is 0x1161 (0x1100: consonant, 0x1161: vowel)
  63     }
  64  * @endcode
  65  */
  66
  67 /**
  68  * @addtogroup CAPI_BASE_UTILS_I18N_UNORMALIZATION_MODULE
  69  * @{
  70  */
  71
  72 /**
  73  * @brief Gets a i18n_unormalizer_h which uses the specified data file and composes or decomposes text according to the specified mode.
  74  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  75  *
  76  * @param[in] package_name @c NULL for ICU built-in data, otherwise application data package name.
  77  * @param[in] name "nfc" or "nfkc" or "nfkc_cf" or the name of the custom data file.
  78  * @param[in] mode The normalization mode (compose or decompose).
  79  * @param[out] normalizer The requested normalizer on success.
  80  *
  81  * @retval #I18N_ERROR_NONE Successful
  82  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
  83  */
  84 int i18n_unormalization_get_instance (const char *package_name, const char *name, i18n_unormalization_mode_e mode,
  85     i18n_unormalizer_h *normalizer);
  86
  87 /**
  88  * @brief Writes the normalized form of the source string to the destination string(replacing its contents).
  89  * @details The source and destination strings must be different buffers.
  90  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  91  *
  92  * @param[in] normalizer i18n normalizer handle.
  93  * @param[in] src The source string.
  94  * @param[in] len The length of the source string, otherwise @c -1 if NULL-terminated.
  95  * @param[out] dest The destination string\n
  96  * Its contents are replaced with normalized @a src.
  97  * @param[in] capacity The number of string_uchar that can be written to @a dest
  98  * @param[out] len_deststr The length of the destination string
  99  *
 100  * @retval #I18N_ERROR_NONE Successful
 101  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 102  */
 103 int i18n_unormalization_normalize (i18n_unormalizer_h normalizer, const i18n_uchar *src, int32_t len, i18n_uchar *dest, int32_t capacity, int32_t *len_deststr);
 104
 105 #ifdef __cplusplus
 106 }
 107 #endif
 108
 109 /**
 110  * @}
 111  * @}
 112  */
 113
 114 #endif  /* __UTILS_I18N_UNORMALIZATION_H__*/