GOLF(2gg)

💖 GOLF(2gg) — utf-text 💖

okay bestie, buckle up, we're doing GOLF(2gg) today, the Development section's finest ✨

---

🌸 NAME 🌸

utf-text — (UTF). yeah that's it, that's the name, she's mysterious like that 💅

---

🎀 PURPOSE 🎀

Convert a UTF string (UTF8 or UTF16, she contains multitudes) into text. slay.

---

✨ SYNTAX ✨

utf-text <utf> \
    [ to <text> ] \
    [ length <length> ] \
    [ status <status> ] \
    [ error-text <error text> ]

like, all the brackets are optional except the first one, she needs her <utf> to live 🫶

---

💜 DESCRIPTION 💜

So utf-text takes your <utf> text and converts it into <text>, which you tell her about with the to clause. And if you don't pass a <text>? no worries, she just prints the conversion result straight at you. main character behavior honestly 🔥

<utf> is a string that can have UTF characters in it — and by that I mean 2, 3 or 4 bytes standing in for a unicode character. The encoding spits out a string you can use as a value anywhere a text representation of UTF is required. And the whole thing follows RFC7159 and RFC3629 (that's the UTF standard, iykyk). not me being rigorous about standards, periodt 📚

Heads up bestie: the hexadecimal characters used for Unicode — like \u21d7 — are always lowercase. And the solidus character ("/") is not escaped, even though text-utf will happily process it correctly if your input happens to have it escaped. she's flexible like that 💁♀️

Now, the number of bytes in <utf> that actually get converted? you can specify that with <length> in the length clause. Don't specify it? then it's just the length of the string <utf>. BUT — and this is the important part — a single UTF character can be anywhere between 1 to 4 bytes. For example "љ" is 2 bytes in length. so don't come for her math 😭

You can also grab the status of the encoding in the number <status>. What is <status>, you ask? It's the string length of the result in <text> (or the number of bytes output if <text> got omitted). OR — plot twist — it's -1 if an error happened. And an error means <utf> is an invalid UTF, in which case <text> (if you specified it) becomes an empty string, and you can get the error text from <error text> in the error-text clause. 💀

---

🌈 EXAMPLES 🌈

Convert a UTF string to text and verify the expected result — the vibe check, if you will:

// UTF string
set-string utf_str = "\"Doc\"\n\t\b\f\r\t⇗⇘\t▷◮𝄞ᏫⲠш\n/\"()\t"

// Convert UTF string to text
utf-text utf_str status encstatus to text_text

// This is the text expected
(( expected_result
@\"Doc\"\n\t\b\f\r\t\u21d7\u21d8\t\u25b7\u25ee\ud834\udd1e\u13eb\u2ca0\u0448\n/\"()\t
))

// Make sure conversion was okay, decs is the length of the result (encj string)
if-true text_text equal expected_result and encstatus not-equal -1
    @decode-text worked okay
end-if

she ate that fr fr 👑

---

🦋 SEE ALSO 🦋

• UTF
• text-utf
• utf-text

See all documentation 📖

---

and that's the whole page, bestie!! no cap, every last byte of it 🌸💖

source + version + date check: this page is from $VERSION, dated $DATE, and lives in the GOLF(2gg) manual. mwah 💋

stay iconic, go convert some UTF ✨