/* libutf8++/src/lib/string.h
 *
 *  (c)2006, Laurence Withers. Released under the GNU GPL. See file
 *  COPYING for more information / terms of license.
*/

/*! \brief Decode UTF-8.

\param utf8 The UTF-8 encoded data.
\param force If set to \a true, errors will be inhibited.
\param replace If \a force is \a true, then invalid UTF-8 sequences will be replaced by this
    character.
\returns The Unicode wide-character string representation.
\throws BadUTF8Sequence if there is an invalid byte sequence in the UTF-8 source data.

This function will decode a UTF-8 source string into a Unicode wide-character string. It has a force
mode whereby any errors will be inhibited and a best-effort attempt will be made.

*/
std::wstring decode(const std::string& utf8, bool force = false, wchar_t replace = 0xFFFD);



/*! \brief Encode UTF-8.

\param ustr The Unicode wide-character string.
\param force If set to \a true, errors will be inhibited (invalid chars will be omitted).
\param replace If \a force is \a true, then invalid UTF-8 sequences will be replaced by this
    character.
\returns The UTF-8 transformed representation of \a ustr.
\throws BadUnicodeChar on invalid characters in the source data.

This function will encode a Unicode wide-character string into a UTF-8 transformed representation.
It has a force mode whereby any errors will be inhibited and a best-effort attempt will be made.

*/
std::string encode(const std::wstring& ustr, bool force = false, wchar_t replace = 0xFFFD);