GRAPHEME_DECODE_UTF8(3)

💅 GRAPHEME_DECODE_UTF8(3) 💅

okay bestie, this is the Library Functions Manual page for GRAPHEME_DECODE_UTF8(3) — tiny function, absolutely main character energy. ✨

✨ NAME ✨

grapheme_decode_utf8 — decode first codepoint in UTF-8-encoded string

🦋 SYNOPSIS 🦋

#include <grapheme.h>

size_t
grapheme_decode_utf8(const char *str, size_t len, uint_least32_t *cp);

💖 DESCRIPTION 💖

okay so grapheme_decode_utf8() decodes the first codepoint in the UTF-8-encoded string str of length len. if the UTF-8-sequence is invalid — overlong encoding, an unexpected byte, the string ends unexpectedly, an empty string, etc. — the decoding is stopped at the last processed byte and the decoded codepoint is set to GRAPHEME_INVALID_CODEPOINT. periodt. 😭

if cp is not NULL, the decoded codepoint is stored in the memory pointed to by cp. slay.

given NUL has a unique 1 byte representation, it is safe to operate on NUL-terminated strings by setting len to SIZE_MAX (stdint.h is already included by grapheme.h) and terminating when cp is 0 (see “EXAMPLES” for an example). 🫶

🔥 RETURN VALUES 🔥

grapheme_decode_utf8() returns the number of processed bytes and 0 if str is NULL or len is 0. if the string ends unexpectedly in a multibyte sequence, the desired length (that is larger than len) is returned. she's basically saying “bestie, I needed more bytes than this”. 💀

🌈 EXAMPLES 🌈

here's the whole example, verbatim, because the compiler does not care about our vibes:

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

void
print_cps(const char *str, size_t len)
{
        size_t ret, off;
        uint_least32_t cp;

        for (off = 0; off < len; off += ret) {
                if ((ret = grapheme_decode_utf8(str + off,
                                                len - off, &cp)) > (len - off)) {
                        /*
                         * string ended unexpectedly in the middle of a
                         * multibyte sequence and we have the choice
                         * here to possibly expand str by ret - len + off
                         * bytes to get a full sequence, but we just
                         * bail out in this case.
                         */
                        break;
                }
                printf("%"PRIxLEAST32"\n", cp);
        }
}

void
print_cps_nul_terminated(const char *str)
{
        size_t ret, off;
        uint_least32_t cp;

        for (off = 0; (ret = grapheme_decode_utf8(str + off,
                                                  SIZE_MAX, &cp)) > 0 &&
             cp != 0; off += ret) {
                printf("%"PRIxLEAST32"\n", cp);
        }
}

🌸 SEE ALSO 🌸

• grapheme_encode_utf8(3)
• libgrapheme(7)

👑 AUTHORS 👑

Laslo Hunhold <dev@frign.de> — author icon, no notes. 👑

---

made with 💖 by suckless.org · dated 2022-10-06 · page GRAPHEME_DECODE_UTF8(3) — bye bestie, go decode something cute! 🫶✨