table of contents
- experimental 2.5.0.20260502-2
| UNICODE::ICONVERT::S(3) | Courier Unicode Library | UNICODE::ICONVERT::S(3) |
NAME¶
unicode::string_converter, unicode::tou_string_converter, unicode::fromu_string_converter - Converting output iterators
SYNOPSIS¶
#include <courier-unicode.h>
std::vector<std::string> strings;
unicode::string_converter converter{
std::back_inserter(strings),
unicode::iso_8859_1,
unicode::utf_8
};
std::vector<std::u32string> ustrings;
auto ustring_iter=std::back_inserter(ustrings);
unicode::tou_string_converter touconverter{
ustring_iter,
unicode::utf_8
};
unicode::fromu_string_converter fromuconverter{
std::back_inserter(strings);
unicode::utf_8
};
*converter++ = "Hello world!\n";
*touconvert++ = "Hello world!\n";
*fromuconverter++ = U"Hello world!\n";
if (converter.errflag)
{
//
}
auto final_value=fromuconverter.iter();
DESCRIPTION¶
These string_converter template classes implement output iterators that iterate over entire string objects. In most cases the template parameters are specified by the defined deduction guides for the templates' constructors.
The first parameter to each template's constructor is another output iterator. Iterating the template instance over each string results in converting the string, and then using the output iterator that was passed to the constructor iterating over the results of the conversion.
Template functionality¶
| unicode template | Iterates over | Parameter iterates over |
| string_converter | std::string | std::string |
| fromu_string_converter | std::u32string | std::string |
| tou_string_converter | std::string | std::u32string |
Additional constructor parameters¶
| unicode template | Additional template parameters | |
| string_converter | "from" and "to" character sets | |
| fromu_string_converter | "to" character set | |
| tou_string_converter | "from" character set |
unicode::string_converter is an output iterator over std::string strings. It takes the std::string strings it iterates over, converts them from one character set to another one, and the output iterator that gets passed to its constructor iterates over each converted std::string.
unicode::fromu_string_converter is an output iterator over std::u32string strings. It takes the std::u32string strings it iterates, converts them to string in the soecufued character set, and the output iterator that gets passed to its constructor iterates over rach converted std::string.
unicode::tou_string_converter is an output iterator over std::string strings. It takes the std::string strings it iterates, converts them to Unicode, using the specified character set, and the output iterator that gets passed to its constructor iterates over each converted std::u32strings.
Template parameters¶
These string_converter templates have one template parameter. In most cases it's sufficient to have it deduced from the constructor. The template parameter is deduced from the first constructor parameter, an output iterator “T” as follows:
T is passed by reference
T is passed by value
If the output iterator gets passed by reference, continuing to iterate the string_converter after the passed in constructor gets destroyed results in undefined behavior. The output iterator must exist as long as the string_converter iterates.
Passing the output iterator by value moves it, and the moved iterator will exist until the string_converter is destroyed.
Template members¶
The iter() method returns the reference to the current value of the iterator that was passed to the constructor. It is typically used to obtain the output iterator that was passed by value to the constructor, after finishing iterating over the converted strings.
The errflag bool indicates whether a conversion error occured during iteration (an iterated-over string could not be converted).
SEE ALSO¶
AUTHOR¶
Sam Varshavchik
| 04/12/2026 | Courier Unicode Library |