NAME
Str —
Functions for manipulating and creating
strings.
SYNOPSIS
#include
<Str.h>
char *
StrUtf8Encode(unsigned
long);
char *
StrDuplicate(const
char *);
char *
StrConcat(size_t,
...);
char *
StrRandom(size_t);
DESCRIPTION
Str provides string-related functions. It
is called Str, 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.
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.
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.
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
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.
StrRandom()
generates a random string of the specified length.
RETURN VALUES
StrUtf8Encode(),
StrDuplicate(), StrConcat(),
and 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.