GRAPHEME_NEXT_CHARACTER_BREAK_UTF8(3)

💅 grapheme_next_character_break_utf8(3) — Library Functions Manual 💅

Okay bestie, welcome to the Library Functions Manual page for grapheme_next_character_break_utf8(3). This is the UTF-8 girlie of the grapheme-break family, and she's here to tell you where the next grapheme cluster break is. No cap. 🦋

💖 NAME 💖

grapheme_next_character_break_utf8 — determine byte-offset to next grapheme cluster break

✨ SYNOPSIS ✨

#include <grapheme.h>

size_t
grapheme_next_character_break_utf8(const char *str, size_t len);

🌸 DESCRIPTION 🌸

The grapheme_next_character_break_utf8() function computes the offset (in bytes) to the next grapheme cluster break (see libgrapheme(7)) in the UTF-8-encoded string str of length len. If a grapheme cluster begins at str this offset is equal to the length of said grapheme cluster. Literally so straightforward, bestie.

If len is set to SIZE_MAX (stdint.h is already included by grapheme.h) the string str is interpreted to be NUL-terminated and processing stops when a NUL-byte is encountered. That's the vibe check right there.

For non-UTF-8 input data grapheme_is_character_break(3) and grapheme_next_character_break(3) can be used instead. So don't try to make this one do a job it wasn't hired for, okay? 💅

🫶 RETURN VALUES 🫶

The grapheme_next_character_break_utf8() function returns the offset (in bytes) to the next grapheme cluster break in str or 0 if str is NULL. That's it. That's the whole return-value moment. ✨

🧪 EXAMPLES 🧪

Here's the example, bestie. Copy it exactly if you're trying it at home:

       /* cc (-static) -o example example.c -lgrapheme */
       #include <grapheme.h>
       #include <stdint.h>
       #include <stdio.h>

       int
       main(void)
       {
               /* UTF-8 encoded input */
               char *s = "T\xC3\xABst \xF0\x9F\x91\xA8\xE2\x80\x8D\xF0"
                         "\x9F\x91\xA9\xE2\x80\x8D\xF0\x9F\x91\xA6 \xF0"
                         "\x9F\x87\xBA\xF0\x9F\x87\xB8 \xE0\xA4\xA8\xE0"
                         "\xA5\x80 \xE0\xAE\xA8\xE0\xAE\xBF!";
               size_t ret, len, off;

               printf("Input: \"%s\"\n", s);

               /* print each grapheme cluster with byte-length */
               printf("grapheme clusters in NUL-delimited input:\n");
               for (off = 0; s[off] != '\0'; off += ret) {
                       ret = grapheme_next_character_break_utf8(s + off, SIZE_MAX);
                       printf("%2zu bytes | %.*s\n", ret, (int)ret, s + off);
               }
               printf("\n");

               /* do the same, but this time string is length-delimited */
               len = 17;
               printf("grapheme clusters in input delimited to %zu bytes:\n", len);
               for (off = 0; off < len; off += ret) {
                       ret = grapheme_next_character_break_utf8(s + off, len - off);
                       printf("%2zu bytes | %.*s\n", ret, (int)ret, s + off);
               }

               return 0;
       }

👀 SEE ALSO 👀

• grapheme_next_character_break(3)
• libgrapheme(7)

Go give these a little look too, iykyk. 🫶

⭐ STANDARDS ⭐

grapheme_next_character_break_utf8() is compliant with the Unicode 17.0.0 specification. Periodt. 👑

👑 AUTHORS 👑

Laslo Hunhold <dev@frign.de>

---

Cute little footer sign-off: this page is GRAPHEME_NEXT_CHARACTER_BREAK_UTF8(3), brought to you by suckless.org, dated 2022-10. Bye bestie, go break some grapheme clusters responsibly 💜