lib/silcutil/silcutf8.h

   1 /*
   2
   3   silcutf8.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2004 - 2005 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_encoded_len
  78  *
  79  * SYNOPSIS
  80  *
  81  *    SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin,
  82  *                                     SilcUInt32 bin_len,
  83  *                                     SilcStringEncoding bin_encoding);
  84  *
  85  * DESCRIPTION
  86  *
  87  *    Returns the length of UTF-8 encoded string if the `bin' of
  88  *    encoding of `bin_encoding' is encoded with silc_utf8_encode.
  89  *    Returns zero (0) on error.
  90  *
  91  ***/
  92 SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin, SilcUInt32 bin_len,
  93                                  SilcStringEncoding bin_encoding);
  94
  95 /****f* silcutil/SilcStrUtilAPI/silc_utf8_decoded_len
  96  *
  97  * SYNOPSIS
  98  *
  99  *    SilcUInt32 silc_utf8_decoded_len(const unsigned char *bin,
 100  *                                     SilcUInt32 bin_len,
 101  *                                     SilcStringEncoding bin_encoding);
 102  *
 103  * DESCRIPTION
 104  *
 105  *    Returns the length of decoded string if the `bin' of encoding of
 106  *    `bin_encoding' is decoded with silc_utf8_decode.  Returns zero (0)
 107  *    on error.
 108  *
 109  ***/
 110 SilcUInt32 silc_utf8_decoded_len(const unsigned char *bin, SilcUInt32 bin_len,
 111                                  SilcStringEncoding bin_encoding);
 112
 113 /****f* silcutil/SilcStrUtilAPI/silc_utf8_valid
 114  *
 115  * SYNOPSIS
 116  *
 117  *    bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len);
 118  *
 119  * DESCRIPTION
 120  *
 121  *    Returns TRUE if the `utf8' string of length of `utf8_len' is valid
 122  *    UTF-8 encoded string, FALSE if it is not UTF-8 encoded string.
 123  *
 124  ***/
 125 bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len);
 126
 127 /****f* silcutil/SilcStrUtilAPI/silc_utf8_strcasecmp
 128  *
 129  * SYNOPSIS
 130  *
 131  *    bool silc_utf8_strcasecmp(const char *s1, const char *s2);
 132  *
 133  * DESCRIPTION
 134  *
 135  *    The silc_utf8_strcasecmp() function compares the two strings s1 and s2,
 136  *    ignoring the case of the characters.  It returns TRUE if the strings
 137  *    match and FALSE if they differ.
 138  *
 139  *    This functions expects NULL terminated UTF-8 strings.  The strings
 140  *    will be casefolded and normalized before comparing.  Certain special
 141  *    Unicode characters will be ignored when comparing.
 142  *
 143  ***/
 144 bool silc_utf8_strcasecmp(const char *s1, const char *s2);
 145
 146 /****f* silcutil/SilcStrUtilAPI/silc_utf8_strncasecmp
 147  *
 148  * SYNOPSIS
 149  *
 150  *    bool silc_utf8_strcasecmp(const char *s1, const char *s2,
 151  *                              SilcUInt32 n);
 152  *
 153  * DESCRIPTION
 154  *
 155  *    The silc_utf8_strcasecmp() function compares the two strings s1 and s2,
 156  *    ignoring the case of the characters.  It returns TRUE if the strings
 157  *    match and FALSE if they differ.
 158  *
 159  *    This functions expects NULL terminated UTF-8 strings.  The strings
 160  *    will be casefolded and normalized before comparing.  Certain special
 161  *    Unicode characters will be ignored when comparing.
 162  *
 163  ***/
 164 bool silc_utf8_strncasecmp(const char *s1, const char *s2, SilcUInt32 n);
 165
 166 #endif /* SILCUTF8_H */