subversion/include/svn_utf.h

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