lib/silcutil/silcutf8.h

   1 /*
   2
   3   silcutf8.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2004 - 2007 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC UTF-8 Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Interface for the UTF-8 Unicode encoding form.  These routines provides
  25  * applications full UTF-8 and Unicode support.  It supports UTF-8 encoding
  26  * to and decoding from myriad of other character encodings.
  27  *
  28  ***/
  29
  30 #ifndef SILCUTF8_H
  31 #define SILCUTF8_H
  32
  33 /****f* silcutil/SilcUTF8API/silc_utf8_encode
  34  *
  35  * SYNOPSIS
  36  *
  37  *    SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len,
  38  *                                SilcStringEncoding bin_encoding,
  39  *                                unsigned char *utf8, SilcUInt32 utf8_size);
  40  *
  41  * DESCRIPTION
  42  *
  43  *    Encodes the string `bin' of which encoding is `bin_encoding' to the
  44  *    UTF-8 encoding into the buffer `utf8' which is of size of `utf8_size'.
  45  *    Returns the length of the UTF-8 encoded string, or zero (0) on error.
  46  *    By default `bin_encoding' is ASCII, and the caller needs to know the
  47  *    encoding of the input string if it is anything else.
  48  *
  49  ***/
  50 SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len,
  51                             SilcStringEncoding bin_encoding,
  52                             unsigned char *utf8, SilcUInt32 utf8_size);
  53
  54 /****f* silcutil/SilcStrUtilAPI/silc_utf8_decode
  55  *
  56  * SYNOPSIS
  57  *
  58  *    SilcUInt32 silc_utf8_decode(const unsigned char *utf8,
  59  *                                SilcUInt32 utf8_len,
  60  *                                SilcStringEncoding bin_encoding,
  61  *                                unsigned char *bin, SilcUInt32 bin_size);
  62  *
  63  * DESCRIPTION
  64  *
  65  *    Decodes UTF-8 encoded string `utf8' to string of which encoding is
  66  *    to be `bin_encoding', into the `bin' buffer of size of `bin_size'.
  67  *    Returns the length of the decoded buffer, or zero (0) on error.
  68  *    By default `bin_encoding' is ASCII, and the caller needs to know to
  69  *    which encoding the output string is to be encoded if ASCII is not
  70  *    desired.
  71  *
  72  ***/
  73 SilcUInt32 silc_utf8_decode(const unsigned char *utf8, SilcUInt32 utf8_len,
  74                             SilcStringEncoding bin_encoding,
  75                             unsigned char *bin, SilcUInt32 bin_size);
  76
  77 /****f* silcutil/SilcStrUtilAPI/silc_utf8_c2w
  78  *
  79  * SYNOPSIS
  80  *
  81  *    SilcUInt32 silc_utf8_c2w(const unsigned char *utf8,
  82  *                             SilcUInt32 utf8_len,
  83  *                             SilcUInt16 *utf8_wide,
  84  *                             SilcUInt32 utf8_wide_size);
  85  *
  86  * DESCRIPTION
  87  *
  88  *    Converts UTF-8 string into UTF-8 wide character string into the
  89  *    `utf8_wide' buffer of size of `utf8_wide_size' in characters.  Returns
  90  *    the length of the UTF-8 wide character string or 0 on error.  The
  91  *    returned length is in characters and not in bytes.  The byte length
  92  *    is twice the returned character length.
  93  *
  94  *    If there is extra space in `utf8_wide' this will NULL terminate the
  95  *    string automatically.
  96  *
  97  ***/
  98 SilcUInt32 silc_utf8_c2w(const unsigned char *utf8, SilcUInt32 utf8_len,
  99                          SilcUInt16 *utf8_wide, SilcUInt32 utf8_wide_size);
 100
 101 /****f* silcutil/SilcStrUtilAPI/silc_utf8_w2c
 102  *
 103  * SYNOPSIS
 104  *
 105  *    SilcUInt32 silc_utf8_w2c(const SilcUInt16 *wide_str,
 106  *                             SilcUInt32 wide_str_len,
 107  *                             unsigned char *utf8, SilcUInt32 utf8_size);
 108  *
 109  * DESCRIPTION
 110  *
 111  *    Converts UTF-8 wide character string into UTF-8 binary string into the
 112  *    `utf8' buffer of size of `utf8_size' in bytes.  Returns the length of
 113  *    the encoded UTF-8 string in bytes or 0 on error.
 114  *
 115  *    If there is extra space in `utf8' this will NULL terminate the string
 116  *    automatically.
 117  *
 118  ***/
 119 SilcUInt32 silc_utf8_w2c(const SilcUInt16 *wide_str, SilcUInt32 wide_str_len,
 120                          unsigned char *utf8, SilcUInt32 utf8_size);
 121
 122 /****f* silcutil/SilcStrUtilAPI/silc_utf8_encoded_len
 123  *
 124  * SYNOPSIS
 125  *
 126  *    SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin,
 127  *                                     SilcUInt32 bin_len,
 128  *                                     SilcStringEncoding bin_encoding);
 129  *
 130  * DESCRIPTION
 131  *
 132  *    Returns the length of UTF-8 encoded string if the `bin' of
 133  *    encoding of `bin_encoding' is encoded with silc_utf8_encode.
 134  *    Returns zero (0) on error.
 135  *
 136  ***/
 137 SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin, SilcUInt32 bin_len,
 138                                  SilcStringEncoding bin_encoding);
 139
 140 /****f* silcutil/SilcStrUtilAPI/silc_utf8_decoded_len
 141  *
 142  * SYNOPSIS
 143  *
 144  *    SilcUInt32 silc_utf8_decoded_len(const unsigned char *bin,
 145  *                                     SilcUInt32 bin_len,
 146  *                                     SilcStringEncoding bin_encoding);
 147  *
 148  * DESCRIPTION
 149  *
 150  *    Returns the length of decoded string if the `bin' of encoding of
 151  *    `bin_encoding' is decoded with silc_utf8_decode.  Returns zero (0)
 152  *    on error.
 153  *
 154  ***/
 155 SilcUInt32 silc_utf8_decoded_len(const unsigned char *bin, SilcUInt32 bin_len,
 156                                  SilcStringEncoding bin_encoding);
 157
 158 /****f* silcutil/SilcStrUtilAPI/silc_utf8_valid
 159  *
 160  * SYNOPSIS
 161  *
 162  *    SilcBool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len);
 163  *
 164  * DESCRIPTION
 165  *
 166  *    Returns TRUE if the `utf8' string of length of `utf8_len' is valid
 167  *    UTF-8 encoded string, FALSE if it is not UTF-8 encoded string.
 168  *
 169  ***/
 170 SilcBool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len);
 171
 172 /****f* silcutil/SilcStrUtilAPI/silc_utf8_strcasecmp
 173  *
 174  * SYNOPSIS
 175  *
 176  *    SilcBool silc_utf8_strcasecmp(const char *s1, const char *s2);
 177  *
 178  * DESCRIPTION
 179  *
 180  *    The silc_utf8_strcasecmp() function compares the two strings s1 and s2,
 181  *    ignoring the case of the characters.  It returns TRUE if the strings
 182  *    match and FALSE if they differ.
 183  *
 184  *    This functions expects NULL terminated UTF-8 strings.  The strings
 185  *    will be casefolded and normalized before comparing.  Certain special
 186  *    Unicode characters will be ignored when comparing.
 187  *
 188  ***/
 189 SilcBool silc_utf8_strcasecmp(const char *s1, const char *s2);
 190
 191 /****f* silcutil/SilcStrUtilAPI/silc_utf8_strncasecmp
 192  *
 193  * SYNOPSIS
 194  *
 195  *    SilcBool silc_utf8_strcasecmp(const char *s1, const char *s2,
 196  *                                  SilcUInt32 n);
 197  *
 198  * DESCRIPTION
 199  *
 200  *    The silc_utf8_strcasecmp() function compares the two strings s1 and s2,
 201  *    ignoring the case of the characters.  It returns TRUE if the strings
 202  *    match and FALSE if they differ.
 203  *
 204  *    This functions expects NULL terminated UTF-8 strings.  The strings
 205  *    will be casefolded and normalized before comparing.  Certain special
 206  *    Unicode characters will be ignored when comparing.
 207  *
 208  ***/
 209 SilcBool silc_utf8_strncasecmp(const char *s1, const char *s2, SilcUInt32 n);
 210
 211 #endif /* SILCUTF8_H */