.Dd $Mdocdate: February 15 2023 $
.Dt STR 3
.Os Telodendria Project
.Sh NAME
.Nm Str
.Nd Functions for manipulating and creating strings.
.Sh SYNOPSIS
.In Str.h
.Ft char *
.Fn StrUtf8Encode "unsigned long"
.Ft char *
.Fn StrDuplicate "const char *"
.Ft char *
.Fn StrConcat "size_t" "..."
.Ft char *
.Fn StrRandom "size_t"
.Sh DESCRIPTION
.Nm
provides string-related functions. It is called
.Nm ,
not String, because some platforms (Windows) do not have
case-sensitive filesystems, so String and string are the same thing, which poses
a problem because string is a standard library header.
.Pp
.Fn StrUtf8Encode
takes a UTF-8 codepoint and encodes it into a string buffer containing between
1 and 4 bytes. The string buffer is allocated on the heap, so it should be freed
when it is no longer needed.
.Pp
.Fn StrDuplicate
duplicates a NULL-terminated string, and returns a new string on the heap. This is
useful when a function takes in a string that it needs to store for long amounts
of time, even perhaps after the original string is gone.
.Pp
.Fn StrConcat
is a var-args function that takes the number of NULL-terminated strings specified
by the first argument, and returns a new string that contains their concatenation.
It works a lot like
.Xr strcat 3 ,
but it takes care of allocating memory big enough to hold all the strings. Any
strings may be NULL. If a string is NULL, it is treated like an empty string.
.Pp
.Fn StrRandom
generates a random string of the specified length.
.Sh RETURN VALUES
.Pp
.Fn StrUtf8Encode ,
.Fn StrDuplicate ,
.Fn StrConcat ,
and
.Fn StrRandom
return a pointer to a NULL-terminated C string on the heap, or NULL if a memory
allocation error occurs. Returned pointers should be freed using the Memory API.
.Sh SEE ALSO
.Xr Memory 3