5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2004 - 2007 Pekka Riikonen
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.
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.
20 /****h* silcutil/SILC UTF-8 Interface
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.
33 /****f* silcutil/SilcUTF8API/silc_utf8_encode
37 * SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len,
38 * SilcStringEncoding bin_encoding,
39 * unsigned char *utf8, SilcUInt32 utf8_size);
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.
50 SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len,
51 SilcStringEncoding bin_encoding,
52 unsigned char *utf8, SilcUInt32 utf8_size);
54 /****f* silcutil/SilcStrUtilAPI/silc_utf8_decode
58 * SilcUInt32 silc_utf8_decode(const unsigned char *utf8,
59 * SilcUInt32 utf8_len,
60 * SilcStringEncoding bin_encoding,
61 * unsigned char *bin, SilcUInt32 bin_size);
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
73 SilcUInt32 silc_utf8_decode(const unsigned char *utf8, SilcUInt32 utf8_len,
74 SilcStringEncoding bin_encoding,
75 unsigned char *bin, SilcUInt32 bin_size);
77 /****f* silcutil/SilcStrUtilAPI/silc_utf8_c2w
81 * SilcUInt32 silc_utf8_c2w(const unsigned char *utf8,
82 * SilcUInt32 utf8_len,
83 * SilcUInt16 *utf8_wide,
84 * SilcUInt32 utf8_wide_size);
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.
94 * If there is extra space in `utf8_wide' this will NULL terminate the
95 * string automatically.
98 SilcUInt32 silc_utf8_c2w(const unsigned char *utf8, SilcUInt32 utf8_len,
99 SilcUInt16 *utf8_wide, SilcUInt32 utf8_wide_size);
101 /****f* silcutil/SilcStrUtilAPI/silc_utf8_w2c
105 * SilcUInt32 silc_utf8_w2c(const SilcUInt16 *wide_str,
106 * SilcUInt32 wide_str_len,
107 * unsigned char *utf8, SilcUInt32 utf8_size);
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.
115 * If there is extra space in `utf8' this will NULL terminate the string
119 SilcUInt32 silc_utf8_w2c(const SilcUInt16 *wide_str, SilcUInt32 wide_str_len,
120 unsigned char *utf8, SilcUInt32 utf8_size);
122 /****f* silcutil/SilcStrUtilAPI/silc_utf8_encoded_len
126 * SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin,
127 * SilcUInt32 bin_len,
128 * SilcStringEncoding bin_encoding);
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.
137 SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin, SilcUInt32 bin_len,
138 SilcStringEncoding bin_encoding);
140 /****f* silcutil/SilcStrUtilAPI/silc_utf8_decoded_len
144 * SilcUInt32 silc_utf8_decoded_len(const unsigned char *bin,
145 * SilcUInt32 bin_len,
146 * SilcStringEncoding bin_encoding);
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)
155 SilcUInt32 silc_utf8_decoded_len(const unsigned char *bin, SilcUInt32 bin_len,
156 SilcStringEncoding bin_encoding);
158 /****f* silcutil/SilcStrUtilAPI/silc_utf8_valid
162 * SilcBool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len);
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.
170 SilcBool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len);
172 /****f* silcutil/SilcStrUtilAPI/silc_utf8_strcasecmp
176 * SilcBool silc_utf8_strcasecmp(const char *s1, const char *s2);
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.
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.
189 SilcBool silc_utf8_strcasecmp(const char *s1, const char *s2);
191 /****f* silcutil/SilcStrUtilAPI/silc_utf8_strncasecmp
195 * SilcBool silc_utf8_strcasecmp(const char *s1, const char *s2,
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.
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.
209 SilcBool silc_utf8_strncasecmp(const char *s1, const char *s2, SilcUInt32 n);
211 #endif /* SILCUTF8_H */