RUNE(3)

💖 RUNE(3) — the rune/UTF glow-up page ✨

okay so bestie, gather round, because this is the RUNE(3) page from the Library Functions Manual and it's literally all about converting between UTF byte streams and runes. it's giving "i speak both languages" main character energy 🦋 and honestly? you're gonna slay this.

🌸 NAME 🌸

runetochar, chartorune, runelen, runenlen, fullrune, utfecpy, utflen, utfnlen, utfrune, utfrrune, utfutf — the whole rune/UTF conversion friend group 💅

✨ SYNOPSIS ✨

#include <u.h>
#include <libc.h>

int    runetochar(char *s, Rune *r)

int    chartorune(Rune *r, char *s)

int    runelen(long r)

int    runenlen(Rune *r, int n)

int    fullrune(char *s, int n)

char*  utfecpy(char *s1, char *es1, char *s2)

int    utflen(char *s)

int    utfnlen(char *s, long n)

char*  utfrune(char *s, long c)

char*  utfrrune(char *s, long c)

char*  utfutf(char *s1, char *s2)

🎀 DESCRIPTION 🎀

so these routines convert to and from a UTF byte stream and runes. that's the whole vibe. two directions, no drama 💖

runetochar copies one rune at r to at most UTFmax bytes starting at s and returns the number of bytes copied. hi bestie, quick PSA: UTFmax, defined as 3 in <libc.h>, is the maximum number of bytes required to represent a rune. so 3. that's the ceiling. don't come for me. ✨

chartorune copies at most UTFmax bytes starting at s to one rune at r and returns the number of bytes copied. but listen — if the input is not exactly in UTF format, chartorune will convert to Runeerror (0xFFFD) and return 1. not me matching that error energy 😭 it's literally the replacement character, iconic behaviour.

runelen returns the number of bytes required to convert r into UTF. simple. clean. obsessed. 🫶

runenlen returns the number of bytes required to convert the n runes pointed to by r into UTF. same deal but for a whole squad of n runes fr fr.

fullrune returns 1 if the string s of length n is long enough to be decoded by chartorune and 0 otherwise. ⚠️ but lowkey important: this does not guarantee that the string contains a legal UTF encoding. it's just a length vibe check, not a legality check, iykyk. this routine is used by programs that obtain input a byte at a time and need to know when a full rune has arrived. patient king behaviour 👑

🌈 the string-lookalike squad 🌈

the following routines are analogous to the corresponding string routines with utf substituted for str and rune substituted for chr. so like, if you know the str/chr versions, you already know the plot twist here 💅

• utfecpy — copies UTF sequences until a null sequence has been copied, but writes no sequences beyond es1. if any sequences are copied, s1 is terminated by a null sequence, and a pointer to that sequence is returned. otherwise, the original s1 is returned. respectful of your boundaries, we stan 🎀
• utflen — returns the number of runes that are represented by the UTF string s. counting queen 🧮
• utfnlen — returns the number of complete runes that are represented by the first n bytes of UTF string s. if the last few bytes of the string contain an incompletely coded rune, utfnlen will not count them; in this way, it differs from utflen, which includes every byte of the string. so like, utfnlen says "no half-finished crumbs 🙅" and utflen says "every byte counts, babes 💀". know the difference or perish (emotionally).
• utfrune / utfrrune — utfrune (utfrrune) returns a pointer to the first (last) occurrence of rune c in the UTF string s, or 0 if c does not occur in the string. first one, last one, both valid. and heads up: the NUL byte terminating a string is considered to be part of the string s. that little NUL is included, no cap. 🤯
• utfutf — returns a pointer to the first occurrence of the UTF string s2 as a UTF substring of s1, or 0 if there is none. and if s2 is the null string, utfutf returns s1. edge case handled, periodt. 💅

🌟 SOURCE 🌟

/src/lib9/utf/rune.c
/src/lib9/utf/utfrune.c

👀 SEE ALSO 👀

• utf(7)
• tcs(1)

bestie if you're still here, you ate that. go forth and convert runes responsibly 💖

okay and for the cute sign-off — this whole thing is from the RUNE(3) Library Functions Manual page, footer and all. mwah, luv u, bye 🎀✨🦋