.. index:: pair: class; EE::Utf<8>
.. _doxid-class_e_e_1_1_utf_3_018_01_4:

template class EE::Utf<8>
=========================

.. toctree::
	:hidden:

Overview
~~~~~~~~

Specialization of the :ref:`Utf <doxid-class_e_e_1_1_utf>` template for UTF-8. :ref:`More...<details-class_e_e_1_1_utf_3_018_01_4>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	#include <utf.hpp>
	
	template <>
	class Utf<8> {
	public:
		// methods
	
		template <typename In>
		static In :ref:`decode<doxid-class_e_e_1_1_utf_3_018_01_4_1a81c001b64b412bc1c1a16e3597604234>`(In begin, In end, :ref:`Uint32<doxid-namespace_e_e_1acb11e434631749f2da0e0004d6038558>`& output, :ref:`Uint32<doxid-namespace_e_e_1acb11e434631749f2da0e0004d6038558>` replacement = 0);
	
		template <typename Out>
		static Out :ref:`encode<doxid-class_e_e_1_1_utf_3_018_01_4_1a63947bdcf2ea1a227959ebfd82f2eeaf>`(:ref:`Uint32<doxid-namespace_e_e_1acb11e434631749f2da0e0004d6038558>` input, Out output, :ref:`Uint8<doxid-namespace_e_e_1aa226754e64fe26f32b5526c7cd36fa75>` replacement = 0);
	
		template <typename In>
		static In :ref:`next<doxid-class_e_e_1_1_utf_3_018_01_4_1a617a6d6704d266f9cfd6241d96b2b27b>`(In begin, In end);
	
		template <typename In>
		static std::size_t :ref:`count<doxid-class_e_e_1_1_utf_3_018_01_4_1ab8f728ac511194484fa9f06486d90bed>`(In begin, In end);
	
		template <typename In, typename Out>
		static Out :ref:`fromAnsi<doxid-class_e_e_1_1_utf_3_018_01_4_1af044a939aef68e001df1d1d0bdac337a>`(In begin, In end, Out output, const std::locale& locale = std::locale());
	
		template <typename In, typename Out>
		static Out :ref:`fromWide<doxid-class_e_e_1_1_utf_3_018_01_4_1a5463c718ed0a26d2bcccfe56a6fd8f01>`(In begin, In end, Out output);
	
		template <typename In, typename Out>
		static Out :ref:`fromLatin1<doxid-class_e_e_1_1_utf_3_018_01_4_1a038374ec182587e5f3b1f99185931427>`(In begin, In end, Out output);
	
		template <typename In, typename Out>
		static Out :ref:`toAnsi<doxid-class_e_e_1_1_utf_3_018_01_4_1a66c843ec1738d8f736d950d418331c7b>`(In begin, In end, Out output, char replacement = 0, const std::locale& locale = std::locale());
	
		template <typename In, typename Out>
		static Out :ref:`toWide<doxid-class_e_e_1_1_utf_3_018_01_4_1a55ad2cdebb22c6d9e43812000951a04a>`(In begin, In end, Out output, wchar_t replacement = 0);
	
		template <typename In, typename Out>
		static Out :ref:`toLatin1<doxid-class_e_e_1_1_utf_3_018_01_4_1a19d53117c3056c8bdde3bc3b107b21a6>`(In begin, In end, Out output, char replacement = 0);
	
		template <typename In, typename Out>
		static Out :ref:`toUtf8<doxid-class_e_e_1_1_utf_3_018_01_4_1ab3ff04d376dbc973b93483ecec7bafb2>`(In begin, In end, Out output);
	
		template <typename In, typename Out>
		static Out :ref:`toUtf16<doxid-class_e_e_1_1_utf_3_018_01_4_1af45122fe243404cbfb4cf73189e40da5>`(In begin, In end, Out output);
	
		template <typename In, typename Out>
		static Out :ref:`toUtf32<doxid-class_e_e_1_1_utf_3_018_01_4_1ac0777f13641dbadcb40a72fd9fa1c834>`(In begin, In end, Out output);
	};
.. _details-class_e_e_1_1_utf_3_018_01_4:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Specialization of the :ref:`Utf <doxid-class_e_e_1_1_utf>` template for UTF-8.

Methods
-------

.. index:: pair: function; decode
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1a81c001b64b412bc1c1a16e3597604234:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In>
	static In decode(In begin, In end, :ref:`Uint32<doxid-namespace_e_e_1acb11e434631749f2da0e0004d6038558>`& output, :ref:`Uint32<doxid-namespace_e_e_1acb11e434631749f2da0e0004d6038558>` replacement = 0)

Decode a single UTF-8 character.

Decoding a character means finding its unique 32-bits code (called the codepoint) in the Unicode standard.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence

	*
		- output

		- Codepoint of the decoded UTF-8 character

	*
		- replacement

		- Replacement character to use in case the UTF-8 sequence is invalid



.. rubric:: Returns:

Iterator pointing to one past the last read element of the input sequence

.. index:: pair: function; encode
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1a63947bdcf2ea1a227959ebfd82f2eeaf:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename Out>
	static Out encode(:ref:`Uint32<doxid-namespace_e_e_1acb11e434631749f2da0e0004d6038558>` input, Out output, :ref:`Uint8<doxid-namespace_e_e_1aa226754e64fe26f32b5526c7cd36fa75>` replacement = 0)

Encode a single UTF-8 character.

Encoding a character means converting a unique 32-bits code (called the codepoint) in the target encoding, UTF-8.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- input

		- Codepoint to encode as UTF-8

	*
		- output

		- Iterator pointing to the beginning of the output sequence

	*
		- replacement

		- Replacement for characters not convertible to UTF-8 (use 0 to skip them)



.. rubric:: Returns:

Iterator to the end of the output sequence which has been written

.. index:: pair: function; next
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1a617a6d6704d266f9cfd6241d96b2b27b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In>
	static In next(In begin, In end)

Advance to the next UTF-8 character.

This function is necessary for multi-elements encodings, as a single character may use more than 1 storage element.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence



.. rubric:: Returns:

Iterator pointing to one past the last read element of the input sequence

.. index:: pair: function; count
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1ab8f728ac511194484fa9f06486d90bed:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In>
	static std::size_t count(In begin, In end)

Count the number of characters of a UTF-8 sequence.

This function is necessary for multi-elements encodings, as a single character may use more than 1 storage element, thus the total size can be different from (begin - end).



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence



.. rubric:: Returns:

Iterator pointing to one past the last read element of the input sequence

.. index:: pair: function; fromAnsi
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1af044a939aef68e001df1d1d0bdac337a:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In, typename Out>
	static Out fromAnsi(In begin, In end, Out output, const std::locale& locale = std::locale())

Convert an ANSI characters range to UTF-8.

The current global locale will be used by default, unless you pass a custom one in the *locale* parameter.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence

	*
		- output

		- Iterator pointing to the beginning of the output sequence

	*
		- locale

		- Locale to use for conversion



.. rubric:: Returns:

Iterator to the end of the output sequence which has been written

.. index:: pair: function; fromWide
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1a5463c718ed0a26d2bcccfe56a6fd8f01:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In, typename Out>
	static Out fromWide(In begin, In end, Out output)

Convert a wide characters range to UTF-8.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence

	*
		- output

		- Iterator pointing to the beginning of the output sequence



.. rubric:: Returns:

Iterator to the end of the output sequence which has been written

.. index:: pair: function; fromLatin1
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1a038374ec182587e5f3b1f99185931427:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In, typename Out>
	static Out fromLatin1(In begin, In end, Out output)

Convert a latin-1 (ISO-8859-1) characters range to UTF-8.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence

	*
		- output

		- Iterator pointing to the beginning of the output sequence



.. rubric:: Returns:

Iterator to the end of the output sequence which has been written

.. index:: pair: function; toAnsi
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1a66c843ec1738d8f736d950d418331c7b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In, typename Out>
	static Out toAnsi(In begin, In end, Out output, char replacement = 0, const std::locale& locale = std::locale())

Convert an UTF-8 characters range to ANSI characters.

The current global locale will be used by default, unless you pass a custom one in the *locale* parameter.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence

	*
		- output

		- Iterator pointing to the beginning of the output sequence

	*
		- replacement

		- Replacement for characters not convertible to ANSI (use 0 to skip them)

	*
		- locale

		- Locale to use for conversion



.. rubric:: Returns:

Iterator to the end of the output sequence which has been written

.. index:: pair: function; toWide
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1a55ad2cdebb22c6d9e43812000951a04a:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In, typename Out>
	static Out toWide(In begin, In end, Out output, wchar_t replacement = 0)

Convert an UTF-8 characters range to wide characters.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence

	*
		- output

		- Iterator pointing to the beginning of the output sequence

	*
		- replacement

		- Replacement for characters not convertible to wide (use 0 to skip them)



.. rubric:: Returns:

Iterator to the end of the output sequence which has been written

.. index:: pair: function; toLatin1
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1a19d53117c3056c8bdde3bc3b107b21a6:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In, typename Out>
	static Out toLatin1(In begin, In end, Out output, char replacement = 0)

Convert an UTF-8 characters range to latin-1 (ISO-8859-1) characters.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence

	*
		- output

		- Iterator pointing to the beginning of the output sequence

	*
		- replacement

		- Replacement for characters not convertible to wide (use 0 to skip them)



.. rubric:: Returns:

Iterator to the end of the output sequence which has been written

.. index:: pair: function; toUtf8
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1ab3ff04d376dbc973b93483ecec7bafb2:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In, typename Out>
	static Out toUtf8(In begin, In end, Out output)

Convert a UTF-8 characters range to UTF-8.

This functions does nothing more than a direct copy; it is defined only to provide the same interface as other specializations of the EE::Utf<> template, and allow generic code to be written on top of it.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence

	*
		- output

		- Iterator pointing to the beginning of the output sequence



.. rubric:: Returns:

Iterator to the end of the output sequence which has been written

.. index:: pair: function; toUtf16
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1af45122fe243404cbfb4cf73189e40da5:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In, typename Out>
	static Out toUtf16(In begin, In end, Out output)

Convert a UTF-8 characters range to UTF-16.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence

	*
		- output

		- Iterator pointing to the beginning of the output sequence



.. rubric:: Returns:

Iterator to the end of the output sequence which has been written

.. index:: pair: function; toUtf32
.. _doxid-class_e_e_1_1_utf_3_018_01_4_1ac0777f13641dbadcb40a72fd9fa1c834:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename In, typename Out>
	static Out toUtf32(In begin, In end, Out output)

Convert a UTF-8 characters range to UTF-32.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- begin

		- Iterator pointing to the beginning of the input sequence

	*
		- end

		- Iterator pointing to the end of the input sequence

	*
		- output

		- Iterator pointing to the beginning of the output sequence



.. rubric:: Returns:

Iterator to the end of the output sequence which has been written