.Dd January 27 2024
.Dt U8GNEXT 3
.Os
.Sh NAME
.Nm u8gnext ,
.Nd iterate over Unicode codepoints
.Sh LIBRARY
.Lb librune
.Sh SYNOPSIS
.In gbrk.h
.Ft size_t
.Fn u8gnext "struct u8view *v" "const char8_t **s" "size_t *n"
.Sh DESCRIPTION
The
.Fn u8gnext
function stores a view of the first grapheme in the buffer
.Fa s
of length
.Fa n
in the structure pointed to by
.Fa v .
It then updates
.Fa s
to point to the next grapheme in the buffer and also updates
.Fa n
accordingly.
.Pp
The
.Vt "struct u8view"
type is described in the
.Xr u8view 3
manual.
.Sh RETURN VALUES
The
.Fn u8gnext
function returns the length of the grapheme iterated over in bytes,
or 0 at the end of iteration.
.Sh EXAMPLES
The following calls to
.Fn u8gnext
iterate over and print all the graphemes in
.Va s .
.Bd -literal -offset indent
#define STRING u8"नमस्कार विश्व"

struct u8view v;
const char8_t *s = STRING;
size_t n = sizeof(STRING) - 1;

while (u8gnext(&v, &s, &n))
	printf("‘%.*s’\en", (int)g.len, g.p);
.Ed
.Sh SEE ALSO
.Xr u8next 3 ,
.Xr u8view 3 ,
.Xr unicode 7 ,
.Xr utf\-8 7
.Sh STANDARDS
.Rs
.%A F. Yergeau
.%D November 2003
.%R RFC 3629
.%T UTF-8, a transformation format of ISO 10646
.Re
.Pp
.Lk https://www.unicode.org/versions/Unicode15.1.0/ \
"The Unicode\(rg Standard Version 15.1.0"
.Sh AUTHORS
.An Thomas Voss Aq Mt mail@thomasvoss.com