textwrap(3)

🎀 NAME 🎀

okay so bestie, meet textwrap — a line-folding (text-wrapping) library with i18n support. yes, the whole manual page is textwrap(3) from the Library Functions Manual, and it's lowkey iconic. 💅

---

✨ SYNOPSIS ✨

#include <textwrap.h>

void textwrap_init(textwrap_t *prop);
void textwrap_columns(textwrap_t *prop, int columns);
void textwrap_tab(textwrap_t *prop, int tab);
void textwrap_head(textwrap_t *prop, const char *head1, const char
*head2);
char *textwrap(const textwrap_t *prop, const char *text);

like, that's the whole vibe right there. 🫶

---

💖 DESCRIPTION 💖

textwrap is a library that wraps your text so it fits in the terminal at a certain width. it's giving Text::Wrap(3pm), fr fr.

but the way this one is different? it supports internationalization. not like other libraries or functions. 💀

1. first of all, it automatically detects the current LC_CTYPE locale and follows it. to enable that, your app must call setlocale(3) in advance. no setlocale, no party. 🙈
2. next up, it supports multibyte encodings like UTF-8 and EUC-JP. in multibyte encodings, one character is made of one or more bytes. yes bestie, one character, multiple bytes, it's a whole thing. ✨
3. third, it supports fullwidth characters like CJK Ideogram, Katakana, Hiragana, and Hangul. these eat up two columns per one character on the terminal. main character energy, taking up double the space. 👑
4. fourth, it supports combining characters like Thai and accents for Latin scripts. these occupy zero columns per one character on the terminal. literally zero, they're just there, vibing. 🦋
5. fifth, it supports languages that don't use whitespaces between words. in those languages, lines can be folded at any place with a small amount of exception (such as before commas). so like, almost anywhere, except the little exceptions. periodt. ⭐

---

🌸 USAGE 🌸

okay so first thing, you gotta prepare a set of parameters as a textwrap_t. make a variable of type textwrap_t, then call textwrap_init() with a pointer to that variable. that's it, that's the entry point. 💖

heads up bestie: members of textwrap_t may change in future. so please use the API functions to modify values of those members. do not go poking at the struct directly, i'm begging. 😭

• textwrap_columns() — specifies the number of columns, aka the width of your terminal. the result string will not have a longer line than this value. the default value is 76. 📏
• textwrap_tab() — specifies the number of columns for the TAB code. the default is 8. 🌈
• textwrap_head() — specifies strings that get added at the top of the top line and at the top of the following lines. the defaults are NULL for head1 and NULL for head2. 🎀

---

the real text-wrapping is performed by textwrap(). the text to be folded is given as text. and text must be encoded in the current LC_CTYPE locale, i.e. ISO-8859-1 in ISO-8859-1 locales, KOI8-R in KOI8-R locales, EUC-JP in EUC-JP locales, UTF-8 in UTF-8 locales, and so on.

ngl you might not be super familiar with the term "LC_CTYPE locale", but bestie, this behavior is under what most users use on UNIX-like systems. so you do not have to convert the encoding of the string. you're already fine. 💜

the text can contain tab code (0x09). the tab gets converted into the proper number of space code (0x20) by textwrap. slay. ✨

---

💅 RETURN VALUE 💅

textwrap() returns the line-folded text. you can free(3) the given value, go off. 🫶

in case of any error while processing the string, the text <ERR> will be appended to the output and processing will be aborted. like it just stops. so watch for that. 💀

---

🔥 EXAMPLE 🔥

#include <stdio.h>
#include <textwrap.h>

main()
{
    textwrap_t property;
    char *text = "This is a sample.\n";
    char *outtext;

    textwrap_init(&property);
    textwrap_columns(&property, 70);
    outtext = textwrap(&property, text);
    printf("%s\n",outtext);
    free(outtext);
}

look at that. 70 columns, init, wrap, print, free. ate. 👑

---

🦋 SEE ALSO 🦋

manual pages of dotextwrap(1), setlocale(3), locale(7), charsets(7), and UTF-8(7). go read them, iykyk. 📚

---

👑 AUTHOR 👑

Tomohiro KUBOTA <kubota@debian.org>. the legend themselves. 💖

---

okay that's the whole page bestie, you're fully caught up 🎀 — this was the textwrap(3) page from the Library Functions Manual, dated 2003-08-16, and honestly it still serves. bye, ily, go wrap some text. 🌸✨💅