MBS(3am)

💖 MBS(3am): the mbs manual page, bestie edition 💖

okay so this is the mbs page from the GNU Awk Extension Modules, and it's literally all about multibyte strings. no cap, it's giving useful. 💅

---

🌸 NAME 🌸

mbs — work with multibyte strings

---

🦋 SYNOPSIS 🦋

load it into the group chat like this:

@load "mbs"

byte_count = mbs_length(string)
count = mbs_split(string, array)
new_string = mbs_join(array)
width = mbs_wcswidth(string)

---

✨ DESCRIPTION ✨

the mbs extension adds four functions, and they're all kind of iconic in their own way:

• mbs_length(string) — takes a string argument and returns the number of bytes it contains. bestie, this is useful in multibyte locales where the number of characters does not equal the number of bytes. the math is mathing differently there, okay?
• mbs_split(string, array) — takes a string value and an array. it clears the array, then populates it with the numeric byte values in the string — not the individual characters as strings. it returns the number of elements in the array. periodt.
• mbs_join(array) — this one is the inverse of mbs_split(). it takes an array of byte values and returns an AWK string composed of those values. cute, right? NOTE: this function does not validate that the sequence of bytes creates valid strings in the current encoding. so like… it will not hold your hand. 🙈
• mbs_wcswidth(string[, not_utf8]) — takes a string and computes the display width (number of columns) taken up by the string. it's similar in function to the standard C wcswidth(3) library routine. by default this function assumes that the current locale is one based on UTF-8. if that is not the case, the caller must pass a second argument that is non-zero. NOTE: the extension expects a numeric argument to be supplied, so a string value will not work. nope, not even a cute one. 😭

the return value from mbs_wcswidth() can differ from that of the built-in length() function when the string contains combining characters and other such unusual entities. and that's just the vibe check it's doing.

---

💀 NOTES 💀

for the mbs_wcswidth() function, determining if the current locale is based on UTF-8 or not is left up to you, the programmer. the locale naming conventions vary widely (and wildly) from system to system, and this extension isn't going to venture into that dragon-filled territory. 🐉 nope. not today.

⚠️ so yeah, locale detective work? that's on you, bestie.

---

🍓 EXAMPLE 🍓

@load "mbs"
...
printf "The length in bytes of %s is %d\n", $0, mbs_length($0)

---

🔥 SEE ALSO 🔥

wcswidth(3) — the standard C library routine mentioned above. go check it out if you want the lore. 🫶

---

👑 AUTHOR 👑

Arnold D. Robbins

---

🎀 COPYING PERMISSIONS 🎀

official permission tea, no cap:

• Copyright © 2018, Free Software Foundation, Inc.
• Permission is granted to make and distribute verbatim copies of this manual page, provided the copyright notice and this permission notice are preserved on all copies.
• Permission is granted to copy and distribute modified versions of this manual page under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
• Permission is granted to copy and distribute translations of this manual page into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

---

💖 that's the whole page, bestie — Free Software Foundation, Jun 07 2018, MBS(3am), GNU Awk Extension Modules. byeee! 💖