// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2008 Emweb bvba, Kessel-Lo, Belgium.
 *
 * See the LICENSE file for terms of use.
 */

#ifndef WSTRING_UTIL_H_
#define WSTRING_UTIL_H_

#include <string>
#include <locale>
#include <Wt/WDllDefs.h>

namespace Wt {
  /*! \brief Convert a narrow to a wide string.
   *
   * Convert a narrow string to a wide string. This method will interpret
   * the input string as being encoded in the given locale (by default the
   * currently configured global C++ locale).
   *
   * \sa narrow(const std::wstring&), fromUTF8(const std::string& s)
   *
   * \relates WString
   */
  extern WT_API std::wstring widen(const std::string& s,
      const std::locale &loc = std::locale());

  /*! \brief Convert a wide to a narrow string.
   *
   * Convert a wide string to a narrow string. This method will encode
   * the characters in the given locale, if possible.
   *
   * In general this will lead to a loss of information. If you wish to
   * preserve all information, you should us toUTF8() instead.
   *
   * \sa widen(const std::string&), toUTF8(const std::wstring& s)
   *
   * \relates WString
   */
  extern WT_API std::string narrow(const std::wstring& s,
      const std::locale &loc = std::locale());

  /*! \brief Decode a UTF8 string a wide string.
   *
   * Decode a UTF8 string to a wide string. In a UTF8 encoded unicode string,
   * some unicode characters are represented in more than one byte.
   * This method will decode to extract the proper unicode characters from
   * the string. The resulting string may thus be shorter (has less characters)
   * than the original, but does not lead to a loss of information.
   *
   * \sa toUTF8(const std::string& s), narrow(const std::wstring&)
   *
   * \relates WString
   */
  extern WT_API std::wstring fromUTF8(const std::string& s);

  /*! \brief Encode a wide string to UTF8.
   *
   * Convert a wide string to UTF8. This method will encode the given
   * wide string in UTF8. This may result in a string that is possibly
   * longer (has more characters), but does not lead to a loss of
   * information.
   *
   * \sa fromUTF8(const std::string& s), narrow(const std::wstring&) 
   *
   * \relates WString
   */
  extern WT_API std::string toUTF8(const std::wstring& s);
}

#endif // WSTRING_UTIL_H_
