TICKIT_UTF8_COUNT(3)

💖 TICKIT_UTF8_COUNT 💖

okay bestie, welcome to tickit_utf8_count(3) — it's from the Library Functions Manual, and it's literally the page that teaches you how to count characters in Unicode strings without losing your whole entire mind. 🧚

---

✨ NAME ✨

tickit_utf8_count, tickit_utf8_countmore — count characters in Unicode strings 👑

---

🌸 SYNOPSIS 🌸

#include <tickit.h>

typedef struct {
    size_t bytes;
    int    codepoints;
    int    graphemes;
    int    columns;
} TickitStringPos;

size_t tickit_utf8_count(const char *str, TickitStringPos *pos,
    const TickitStringPos *limit);
size_t tickit_utf8_countmore(const char *str, TickitStringPos *pos,
    const TickitStringPos *limit);

size_t tickit_utf8_ncount(const char *str, size_t len,
    TickitStringPos *pos, const TickitStringPos *limit);
size_t tickit_utf8_ncountmore(const char *str, size_t len,
    TickitStringPos *pos, const TickitStringPos *limit);

Link with -ltickit.

---

🦋 DESCRIPTION 🦋

tickit_utf8_count() counts characters in the given Unicode string, and that string must be in UTF-8 encoding, no exceptions bestie. It starts at the very beginning of the string and counts forward over codepoints and graphemes, incrementing the counters in pos until it reaches a limit. 🫶

It will not go further than any of the limits given by the limits structure — and the value -1 means "no limit of that type", so that's your "go off, no cap" setting.

It will never split a codepoint in the middle of a UTF-8 sequence, and it will never split a grapheme between its codepoints. Which means — plot twist — it's totally possible for the function to return before any of the limits have been reached, if the next whole grapheme would involve going past at least one of the specified limits. 😭 It'll also stop when it reaches the end of str. And it returns the total number of bytes it has counted over.

Here's the member-by-member tea:

• bytes — counts UTF-8 bytes which encode individual codepoints. Example time: the Unicode character U+00E9 is encoded by two bytes 0xc3, 0xa9; so it would bump the bytes counter by 2 and the codepoints counter by 1. ✨
• codepoints — counts individual Unicode codepoints. Simple. Iconic.
• graphemes — counts whole composed graphical clusters of codepoints, where combining accents that count as individual codepoints do not count as separate graphemes. Example: the codepoint sequence U+0065 U+0301 would increment the codepoint counter by 2 and the graphemes counter by 1. the way that works is so satisfying honestly 💅
• columns — counts the number of screen columns consumed by the graphemes. Most graphemes consume only 1 column, but some are defined in Unicode to consume 2.

tickit_utf8_countmore() is similar to tickit_utf8_count() except it will not zero any of the counters before it starts. So it can continue counting right where a previous call finished, like a relay race but for bytes. 🏃‍♀️ In particular, it will assume that it is starting at the beginning of a UTF-8 sequence that begins a new grapheme.

⚠️ and it will not check these facts, and the behavior is undefined if these assumptions do not hold. it's giving "trust me bro" and honestly, don't. 🙈

It will begin at the offset given by pos.bytes.

The tickit_utf8_ncount() and tickit_utf8_ncountmore() variants are similar except that they read no more than len bytes from the string and do not require it to be NUL terminated. They will still stop at a NUL byte if one is found before len bytes have been read. 🎀

And here's the part where you hold my hand: these functions will all immediately abort if any C0 or C1 control byte other than NUL is encountered, returning the value -1. In this circumstance, the pos structure will still be updated with the progress so far. so at least you get the receipts. 💀

---

🌈 USAGE 🌈

Typically, these functions would be used either of two ways. two moods, one function, we love to see it.

1. When given a value in limit.bytes (or no limit and simply using string termination), tickit_utf8_count() will yield the width of the given string in terminal columns, in the pos.columns field. 📏
2. When given a value in limit.columns, tickit_utf8_count() will yield the number of bytes of that string that will consume the given space on the terminal. 🔥

---

👑 RETURN VALUE 👑

tickit_utf8_count() and tickit_utf8_countmore() return the number of bytes they have skipped over this call, or -1 if they encounter a C0 or C1 byte other than NUL.

---

💜 SEE ALSO 💜

• tickit_stringpos_zero(3)
• tickit_stringpos_limit_bytes(3)
• tickit_utf8_mbswidth(3)
• tickit(7)

---

okay that's the whole page bestie, you ate it. 🍓 this was TICKIT_UTF8_COUNT(3) from the Library Functions Manual, and yes, the footer really is just the page name again — she's a minimalist, she's consistent, we stan. mwah 💅💖