src/TortoiseMerge/svninclude/svn_utf.h

   1 /**\r
   2  * @copyright\r
   3  * ====================================================================\r
   4  * Copyright (c) 2000-2004, 2008 CollabNet.  All rights reserved.\r
   5  *\r
   6  * This software is licensed as described in the file COPYING, which\r
   7  * you should have received as part of this distribution.  The terms\r
   8  * are also available at http://subversion.tigris.org/license-1.html.\r
   9  * If newer versions of this license are posted there, you may use a\r
  10  * newer version instead, at your option.\r
  11  *\r
  12  * This software consists of voluntary contributions made by many\r
  13  * individuals.  For exact contribution history, see the revision\r
  14  * history and logs, available at http://subversion.tigris.org/.\r
  15  * ====================================================================\r
  16  * @endcopyright\r
  17  *\r
  18  * @file svn_utf.h\r
  19  * @brief UTF-8 conversion routines\r
  20  * Whenever a conversion routine cannot convert to or from UTF-8, the\r
  21  * error returned has code @c APR_EINVAL.\r
  22  */\r
  23 \r
  24 \r
  25 \f\r
  26 #ifndef SVN_UTF_H\r
  27 #define SVN_UTF_H\r
  28 \r
  29 #include <apr_pools.h>\r
  30 #include <apr_xlate.h>  /* for APR_*_CHARSET */\r
  31 \r
  32 #include "svn_types.h"\r
  33 #include "svn_string.h"\r
  34 \r
  35 #ifdef __cplusplus\r
  36 extern "C" {\r
  37 #endif /* __cplusplus */\r
  38 \r
  39 #define SVN_APR_LOCALE_CHARSET APR_LOCALE_CHARSET\r
  40 #define SVN_APR_DEFAULT_CHARSET APR_DEFAULT_CHARSET\r
  41 \r
  42 /**\r
  43  * Initialize the UTF-8 encoding/decoding routines.\r
  44  * Allocate cached translation handles in a subpool of @a pool.\r
  45  *\r
  46  * @note It is optional to call this function, but if it is used, no other\r
  47  * svn function may be in use in other threads during the call of this\r
  48  * function or when @a pool is cleared or destroyed.\r
  49  * Initializing the UTF-8 routines will improve performance.\r
  50  *\r
  51  * @since New in 1.1.\r
  52  */\r
  53 void\r
  54 svn_utf_initialize(apr_pool_t *pool);\r
  55 \r
  56 /** Set @a *dest to a utf8-encoded stringbuf from native stringbuf @a src;\r
  57  * allocate @a *dest in @a pool.\r
  58  */\r
  59 svn_error_t *\r
  60 svn_utf_stringbuf_to_utf8(svn_stringbuf_t **dest,\r
  61                           const svn_stringbuf_t *src,\r
  62                           apr_pool_t *pool);\r
  63 \r
  64 \r
  65 /** Set @a *dest to a utf8-encoded string from native string @a src; allocate\r
  66  * @a *dest in @a pool.\r
  67  */\r
  68 svn_error_t *\r
  69 svn_utf_string_to_utf8(const svn_string_t **dest,\r
  70                        const svn_string_t *src,\r
  71                        apr_pool_t *pool);\r
  72 \r
  73 \r
  74 /** Set @a *dest to a utf8-encoded C string from native C string @a src;\r
  75  * allocate @a *dest in @a pool.\r
  76  */\r
  77 svn_error_t *\r
  78 svn_utf_cstring_to_utf8(const char **dest,\r
  79                         const char *src,\r
  80                         apr_pool_t *pool);\r
  81 \r
  82 \r
  83 /** Set @a *dest to a utf8 encoded C string from @a frompage encoded C\r
  84  * string @a src; allocate @a *dest in @a pool.\r
  85  *\r
  86  * @since New in 1.4.\r
  87  */\r
  88 svn_error_t *\r
  89 svn_utf_cstring_to_utf8_ex2(const char **dest,\r
  90                             const char *src,\r
  91                             const char *frompage,\r
  92                             apr_pool_t *pool);\r
  93 \r
  94 \r
  95 /** Like svn_utf_cstring_to_utf8_ex2() but with @a convset_key which is\r
  96  * ignored.\r
  97  *\r
  98  * @deprecated Provided for backward compatibility with the 1.3 API.\r
  99  */\r
 100 SVN_DEPRECATED\r
 101 svn_error_t *\r
 102 svn_utf_cstring_to_utf8_ex(const char **dest,\r
 103                            const char *src,\r
 104                            const char *frompage,\r
 105                            const char *convset_key,\r
 106                            apr_pool_t *pool);\r
 107 \r
 108 \r
 109 /** Set @a *dest to a natively-encoded stringbuf from utf8 stringbuf @a src;\r
 110  * allocate @a *dest in @a pool.\r
 111  */\r
 112 svn_error_t *\r
 113 svn_utf_stringbuf_from_utf8(svn_stringbuf_t **dest,\r
 114                             const svn_stringbuf_t *src,\r
 115                             apr_pool_t *pool);\r
 116 \r
 117 \r
 118 /** Set @a *dest to a natively-encoded string from utf8 string @a src;\r
 119  * allocate @a *dest in @a pool.\r
 120  */\r
 121 svn_error_t *\r
 122 svn_utf_string_from_utf8(const svn_string_t **dest,\r
 123                          const svn_string_t *src,\r
 124                          apr_pool_t *pool);\r
 125 \r
 126 \r
 127 /** Set @a *dest to a natively-encoded C string from utf8 C string @a src;\r
 128  * allocate @a *dest in @a pool.\r
 129  */\r
 130 svn_error_t *\r
 131 svn_utf_cstring_from_utf8(const char **dest,\r
 132                           const char *src,\r
 133                           apr_pool_t *pool);\r
 134 \r
 135 \r
 136 /** Set @a *dest to a @a topage encoded C string from utf8 encoded C string\r
 137  * @a src; allocate @a *dest in @a pool.\r
 138  *\r
 139  * @since New in 1.4.\r
 140  */\r
 141 svn_error_t *\r
 142 svn_utf_cstring_from_utf8_ex2(const char **dest,\r
 143                               const char *src,\r
 144                               const char *topage,\r
 145                               apr_pool_t *pool);\r
 146 \r
 147 \r
 148 /** Like svn_utf_cstring_from_utf8_ex2() but with @a convset_key which is\r
 149  * ignored.\r
 150  *\r
 151  * @deprecated Provided for backward compatibility with the 1.3 API.\r
 152  */\r
 153 SVN_DEPRECATED\r
 154 svn_error_t *\r
 155 svn_utf_cstring_from_utf8_ex(const char **dest,\r
 156                              const char *src,\r
 157                              const char *topage,\r
 158                              const char *convset_key,\r
 159                              apr_pool_t *pool);\r
 160 \r
 161 \r
 162 /** Return a fuzzily native-encoded C string from utf8 C string @a src,\r
 163  * allocated in @a pool.  A fuzzy recoding leaves all 7-bit ascii\r
 164  * characters the same, and substitutes "?\\XXX" for others, where XXX\r
 165  * is the unsigned decimal code for that character.\r
 166  *\r
 167  * This function cannot error; it is guaranteed to return something.\r
 168  * First it will recode as described above and then attempt to convert\r
 169  * the (new) 7-bit UTF-8 string to native encoding.  If that fails, it\r
 170  * will return the raw fuzzily recoded string, which may or may not be\r
 171  * meaningful in the client's locale, but is (presumably) better than\r
 172  * nothing.\r
 173  *\r
 174  * ### Notes:\r
 175  *\r
 176  * Improvement is possible, even imminent.  The original problem was\r
 177  * that if you converted a UTF-8 string (say, a log message) into a\r
 178  * locale that couldn't represent all the characters, you'd just get a\r
 179  * static placeholder saying "[unconvertible log message]".  Then\r
 180  * Justin Erenkrantz pointed out how on platforms that didn't support\r
 181  * conversion at all, "svn log" would still fail completely when it\r
 182  * encountered unconvertible data.\r
 183  *\r
 184  * Now for both cases, the caller can at least fall back on this\r
 185  * function, which converts the message as best it can, substituting\r
 186  * "?\\XXX" escape codes for the non-ascii characters.\r
 187  *\r
 188  * Ultimately, some callers may prefer the iconv "//TRANSLIT" option,\r
 189  * so when we can detect that at configure time, things will change.\r
 190  * Also, this should (?) be moved to apr/apu eventually.\r
 191  *\r
 192  * See http://subversion.tigris.org/issues/show_bug.cgi?id=807 for\r
 193  * details.\r
 194  */\r
 195 const char *\r
 196 svn_utf_cstring_from_utf8_fuzzy(const char *src,\r
 197                                 apr_pool_t *pool);\r
 198 \r
 199 \r
 200 /** Set @a *dest to a natively-encoded C string from utf8 stringbuf @a src;\r
 201  * allocate @a *dest in @a pool.\r
 202  */\r
 203 svn_error_t *\r
 204 svn_utf_cstring_from_utf8_stringbuf(const char **dest,\r
 205                                     const svn_stringbuf_t *src,\r
 206                                     apr_pool_t *pool);\r
 207 \r
 208 \r
 209 /** Set @a *dest to a natively-encoded C string from utf8 string @a src;\r
 210  * allocate @a *dest in @a pool.\r
 211  */\r
 212 svn_error_t *\r
 213 svn_utf_cstring_from_utf8_string(const char **dest,\r
 214                                  const svn_string_t *src,\r
 215                                  apr_pool_t *pool);\r
 216 \r
 217 #ifdef __cplusplus\r
 218 }\r
 219 #endif /* __cplusplus */\r
 220 \r
 221 #endif /* SVN_UTF_H */\r