forked from Telodendria/Telodendria
56 lines
1.7 KiB
Groff
56 lines
1.7 KiB
Groff
.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
|