src/support/unicode.h

   1 // -*- C++ -*-
   2 /**
   3  * \file unicode.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Lars Gullik Bjønnes
   8  *
   9  * Full author contact details are available in file CREDITS.
  10  *
  11  * A collection of unicode conversion functions, using iconv.
  12  */
  13
  14 #ifndef LYX_SUPPORT_UNICODE_H
  15 #define LYX_SUPPORT_UNICODE_H
  16
  17 #include "support/strfwd.h"
  18 #include "support/unique_ptr.h"
  19
  20 #include <cstddef>
  21 #include <string>
  22 #include <vector>
  23
  24
  25 namespace lyx {
  26
  27 /**
  28  * Wrapper for iconv(3).
  29  *
  30  * According to the POSIX standard, all specified functions are thread-safe,
  31  * with some exceptions. The iconv() function is not listed as an exception:
  32  * http://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xsh_chap02.html#tag_22_02_09_09
  33  * http://man7.org/linux/man-pages/man7/pthreads.7.html
  34  *
  35  * Therefore, you can use as many instances of this class in parallel as you
  36  * like. However, you need to ensure that each instance is only used by one
  37  * thread at any given time. If this condition is not met you get nasty
  38  * mixtures of different thread data as in bug 7240.
  39  *
  40  * From a performance point of view it is best to use one static instance
  41  * per thread for each in/out encoding pair. This can e.g. be achieved by
  42  * using helpers for thread-local storage such as QThreadStorage or
  43  * boost::thread_specific_ptr. A single static instance protected by a mutex
  44  * would work as well, and might be preferrable for exotic encoding pairs.
  45  * Creating local IconvProcessor instances should be avoided because of the
  46  * overhead in iconv_open().
  47  */
  48 class IconvProcessor
  49 {
  50         /// open iconv.
  51         /// \return true if the processor is ready to use.
  52         bool init();
  53         std::string const tocode_;
  54         std::string const fromcode_;
  55         struct Handler;
  56         unique_ptr<Handler> h_;
  57 public:
  58         IconvProcessor(std::string tocode, std::string fromcode);
  59         /// convert any data from \c fromcode to \c tocode unicode format.
  60         /// \return the number of bytes of the converted output buffer.
  61         int convert(char const * in_buffer, size_t in_size,
  62                 char * out_buffer, size_t max_out_size);
  63         /// target encoding
  64         std::string to() const { return tocode_; }
  65 };
  66
  67 /// Get the global IconvProcessor instance of the current thread for
  68 /// utf8->ucs4 conversions
  69 IconvProcessor & utf8ToUcs4();
  70
  71 // A single codepoint conversion for utf8_to_ucs4 does not make
  72 // sense, so that function is left out.
  73
  74 std::vector<char_type> utf8_to_ucs4(std::vector<char> const & utf8str);
  75
  76 std::vector<char_type> utf8_to_ucs4(char const * utf8str, size_t ls);
  77
  78 // utf16_to_ucs4
  79
  80 std::vector<char_type> utf16_to_ucs4(unsigned short const * s, size_t ls);
  81
  82 // ucs4_to_utf16
  83
  84 std::vector<unsigned short> ucs4_to_utf16(char_type const * s, size_t ls);
  85
  86 /// Get the global IconvProcessor instance of the current thread for
  87 /// ucs4->utf8 conversions
  88 IconvProcessor & ucs4ToUtf8();
  89
  90 // ucs4_to_utf8
  91
  92 std::vector<char> ucs4_to_utf8(char_type c);
  93
  94 std::vector<char> ucs4_to_utf8(std::vector<char_type> const & ucs4str);
  95
  96 std::vector<char> ucs4_to_utf8(char_type const * ucs4str, size_t ls);
  97
  98 /// convert \p s from encoding \p encoding to ucs4.
  99 /// \p encoding must be a valid iconv 8bit encoding
 100 std::vector<char_type>
 101 eightbit_to_ucs4(char const * s, size_t ls, std::string const & encoding);
 102
 103 /// convert \p s from ucs4 to encoding \p encoding.
 104 /// \p encoding must be a valid iconv 8bit encoding
 105 std::vector<char> ucs4_to_eightbit(char_type const * ucs4str,
 106         size_t ls, std::string const & encoding);
 107
 108 /// convert ucs4 character \p c to encoding \p encoding.
 109 /// \p encoding must be a valid iconv 8bit encoding
 110 char ucs4_to_eightbit(char_type c, std::string const & encoding);
 111
 112 ///
 113 void ucs4_to_multibytes(char_type ucs4, std::vector<char> & out,
 114         std::string const & encoding);
 115
 116 extern char const * ucs4_codeset;
 117
 118 /// How many bytes does one UCS4 code point use at most in encoding \p encoding?
 119 int max_encoded_bytes(std::string const & encoding);
 120
 121 } // namespace lyx
 122
 123 #endif