UNICODE::ICONVERT::S(3)

💖 UNICODE::ICONVERT::S(3) 💖

okay so bestie, this page lives in the Courier Unicode Library, and it's about three lil template classes that are output iterators which eat whole strings at a time. no cap. let's get into it 🦋

---

✨ 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 🌸

so these string_converter template classes are output iterators that iterate over entire string objects, like, whole strings at a time, not one char at a time. it's giving ✨efficiency✨. and in most cases the template parameters get figured out for you by the defined deduction guides on the templates' constructors — the compiler just does it, no thoughts, head empty, slay.

the first parameter to every one of these constructors is another output iterator. you iterate the template instance over each string, it converts that string, and then it hands the converted results off to the output iterator you passed to the constructor. chain reaction, main character energy 🔥

🎀 Template functionality 🎀

• string_converter — iterates over std::string, and the parameter iterates over std::string
• fromu_string_converter — iterates over std::u32string, and the parameter iterates over std::string
• tou_string_converter — iterates over std::string, and the parameter iterates over std::u32string

🎀 Additional constructor parameters 🎀

• string_converter — takes additional template parameters: "from" and "to" character sets
• fromu_string_converter — takes an additional template parameter: the "to" character set
• tou_string_converter — takes an additional template parameter: the "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 then the output iterator that got passed to its constructor iterates over each converted std::string. converting AND iterating? she does both. 💅

unicode::fromu_string_converter is an output iterator over std::u32string strings. it takes the std::u32string strings it iterates, converts them to a string in the specified character set, and the output iterator that got passed to its constructor iterates over each converted std::string. periodt.

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 got passed to its constructor iterates over each converted std::u32string. iconic.

---

🦋 Template parameters 🦋

these string_converter templates have one template parameter. in most cases it's totally enough to just let it be deduced from the constructor. the template parameter is deduced from the first constructor parameter, an output iterator T, and it goes like this:

• T is passed by reference — the template parameter is <T &>
• T is passed by value — the template parameter is <T>

⚠️ bestie, listen. if the output iterator gets passed by reference, and you keep iterating the string_converter after the passed-in constructor gets destroyed, that's undefined behavior. not a vibe. the output iterator has to exist for as long as the string_converter iterates. no exceptions, fr fr 😭

passing the output iterator by value moves it, and the moved iterator will exist until the string_converter is destroyed. so it just hangs out with you. adorable 🫶

---

💜 Template members 💜

• iter() — this method returns a reference to the current value of the iterator that was passed to the constructor. you'd typically use it to grab the output iterator that was passed by value to the constructor, after you're done iterating over the converted strings. so useful, obsessed 💖
• errflag — a bool that tells you whether a conversion error occurred during iteration (meaning: an iterated-over string could not be converted). it's your little truth-teller 🍓

---

⭐ SEE ALSO ⭐

• courier-unicode(7)

---

👑 AUTHOR 👑

Sam Varshavchik

• Author

---

okay that's the whole page, you're welcome 💅✨ go write some converters, bestie. this was Courier Unicode Library, dated 04/12/2026 — mwah, xoxo 🎀🦋💖