Welcome to yasldoc

Contents:

API Documentation

Data structures

There are two data structures used in yasl. The first which is what all code using yasl strings use is yastr which is a char * typedef. Since it’s just a typedef its use is not strictly necessary, but is recommended to make it clear that the given string is a yasl string.

When a function that has the yastr return type returns NULL it is signifying an error condition and all functions noted as possibly returning NULL must have their return value checked on each invocation. Passing a NULL pointer as an argument to a function expecting a yastr is undefined and invalid.

The second data structure is the following struct:

struct yastrhdr {
    size_t len;
    size_t free;
    char buf[];
};

The yastrhdr struct is the header that exists before all yasl strings, and which keeps track of the length and amount of free space available in the string. All instances of yastr are really pointers to to the char buffer in a yastrhdr struct.

Due to the yastr being a pointer to a member of a yastr struct all internal functions in yasl can use pointer arithmetic to get a pointer to the yastrhdr of a given yastr string, which is why all functions in yasl only requires a yastr instead of a yastrhdr

All yastr strings have a NULL byte at the end of the string, located at the byte after the full length of the string, so a yastr will always be safe to pass to functions expecting C strings. However, since yastr strings are binary-safe the string may contain NULL characters in it.

Initialization

The initialization group contains the functions used to create new yastr strings.

yaslnew

yastr yaslnew(const void * init, size_t initlen)

The yaslnew() function allocates a new yastr of size initlen and using the contents of the init argument to initialize the string with.

If the init argument is a NULL pointer the string will be initialized with initlen NULL bytes

This function may return NULL if the malloc() call failed.

yaslauto

yastr yaslauto(const char * s)

The yaslauto() function uses strlen to get the length of the char * given and then uses yaslnew() to create a new yastr. If the char * given is an empty string it will fall back to creating a yastr of size zero.

yasldup

yastr yasldup(const yastr s)

The yasldup() functions takes a yastr and creates and returns a new yastr using the given string as an initializing value.

yaslempty

yastr yaslempty(void)

The yaslempty() function creates and returns an empty yastr

While the available length of the string is 0 there is still a NULL byte at the end of every yastr string.

yaslfromlonglong

yastr yaslfromlonglong(long long value)

The yaslfromlonglong() function creates and returns a yastr from a long long value. This could be done with yaslcatprintf() but the implementation used in yaslfromlonglong() is more specialized and thus faster.

Querying

yaslcmp

int yaslcmp(const yastr s1, const yastr s2)

The yaslcmp() function takes two yastr‘s and compares them using memcmp(). Its return value is lesser than, equal to, or greater than zero if the first string is lesser than, equal to, or greater than the second string.

If two strings share an identical prefix, but one of them has additional characters at the end, the longer string is considered to be greater than the shorter one.

yaslavail

size_t yaslavail(const yastr s)

The yaslavail() function takes a yastr and returns the amount of space left available in the string’s buffer before it will need to be realloc()‘ed. This operation is fast since it just needs to return the value of the avail member of the yastrhdr struct, which is updated every time the yastr is modified.

yasllen

size_t yasllen(const yastr s)

The yasllen() function takes a yastr and returns the length of the string. This operation is fast and safe since it just needs to return the value of the len member of the yastrhdr which is updated every time the yastr is modified, and thus the length is always known.

Modification

This group contains all the functions used for modification of yastr strings, with the exception of the concatenation functions in the next group.

yaslclear

void yaslclear(yastr s)

The yaslclear() function takes a yastr and clears it, setting the length to zero and the first char to NULL. This function does not either realloc() or set all of the string to NULL bytes, so it’s fast, but it will also not suffice if you need the string to be reset to all NULL bytes.

yaslgrowzero

yastr yaslgrowzero(yastr s, size_t len)

The yaslgrowzero() function takes a yastr and a length arguments. If the length argument is bigger than the current length of the string it will grow the string to the given length and set all of the new length to zero, but will not touch the content of original length of the string.

If the given length is smaller than the current length no operation is performed.

This function may realloc() the string so all references to the original yastr should be treated as invalid and should be replaced with the one returned by this function.

yaslcpylen

yastr yaslcpylen(yastr s, const char * t, size_t len)

The yaslcpylen() function copies len bytes from the given char * to the given yastr.

This function may realloc() the string so all references to the original yastr should be treated as invalid and should be replaced with the one returned by this function.

This function may return NULL in case the realloc() call failed, in which case the original yastr references are still valid and should be used.

If the t argument to the yaslcpylen() function is a NULL pointer, no operation is performed and the function will return NULL.

yaslcpy

yastr yaslcpy(yastr s, const char * t)

The yaslcpy() function copies the contents of the given char * to a yastr. It is identical to the yaslcpylen() function but instead of explicitly giving a length parameter it will run the strlen() function on the char * before calling the yaslcpylen() function.

This function may realloc() the string so all references to the original yastr should be treated as invalid and should be replaced with the one returned by the function.

This function may return NULL in case the realloc() call failed, in which case the original yastr references are still valid and should be used.

If the t argument to the yaslcpy() function is a NULL pointer, no operation is performed and the function will return NULL.

yasljoin

yastr yasljoin(char ** argv, int argc, char * sep, size_t seplen)
The yasljoin() function joins an array of C strings using the specified
C string separator, and returns the resulting string as a yastr.

If the argv or sep arguments to the yasljoin() function are NULL pointers, no operation is performed and the function will return NULL.

yasljoinyasl

yastr yasljoinyasl(yastr * argv, int argc, const char * sep, size_t seplen)

The yasljoinyasl() function join an array of yastr using the specified C string separator, and returns the resulting string as a new yastr.

If the sep argument to the yasljoinyasl() function is a NULL pointer, no operation is performed and the function will return NULL.

yaslmapchars

yastr yaslmapchars(yastr s, const char * from, const char * to, size_t setlen)

The yaslmapchars() function replaces every occurrence of the set of characters in the from C string to the corresponding character in the to C string.

Since this function just maps one set of characters to another set of characters it will never change the length of the string, so the existing references to the string will continue being valid.

If the from or to arguments to the yaslmapchars() function are NULL pointers, no operation is performed and the function will return NULL.

Examples
yastr string = yaslauto("hello");
yaslmapchars(string, "ho", "01", 2);

yaslrange

void yaslrange(yastr s, ptrdiff_t start, ptrdiff_t end)

The yaslrange() function will destructively modify the yastr to only contain the substring marked by the given start and end arguments. The start and end arguments may be negative, where -1 means the last character, et cetera. The given argument ranges are inclusive, so the start and end characters will be included in the resulting string.

The string is modified in-place, so no allocation is required.

Examples
yastr string = yaslauto("Hello, World");
yaslrange(string, 1, -1);
printf("%s\n", string);

Will print ello, World

yasltolower

void yasltolower(yastr s)

The yasltolower() function takes a yastr and runs the tolower() function on each char of the string.

yasltoupper

void yasltoupper(yastr s)

The yasltoupper() function takes a yastr and runs the touppeupper() function on each char of the string.

yasltrim

void yasltrim(yastr s, const char * cset)

The yasltrim() function will trim the characters composed of just the characters found in the cset C string from the beginning and end of the given yastr.

If the cset argument to the yasltrim() function is a NULL pointer, no operation is performed and the function will return.

Examples
yastr string = yaslauto("AA...AA.a.aa.aHelloWorld     :::");
yasltrim(string, "Aa. :");
printf("%s\n", string);

Will print HelloWorld

yaslupdatelen

void yaslupdatelen(yastr s)

The yaslupdatelen() updates the len of the string to the value returned by strlen(). This function is useful when the yastr has been modified by a function not aware of yasl strings, but since strlen() works on C strings it will not work properly on strings containing NULL characters.

Examples
yastr string = yaslauto("foobar");
string[2] = '\0';
yaslupdatelen(string);
printf("%d\n", yasllen(string));

The output will be “2”, but if we comment out the call to yaslupdatelen() the output will be “6” as the string was modified but the logical length remains 6 bytes.

yaslsplitargs

yastr * yaslsplitargs(const char * line, int * argc)

The yaslsplitargs() function splits a C string into an array of yastr strings in the same way a shell would. The argc pointer is set to the number of arguments in the yastr array returned.

The caller should free the resulting array of yastr strings using the yaslfreesplitres() function.

To revert the operations of this functions and convert a string back into a quoted string that yaslsplitargs() is able to parse you can use the yaslcatrepr() function.

This function will return NULL if the input contains unbalanced quoted or closed quotes followed by a non-space character.

If the line or argc arguments to the yaslsplitargs() function are NULL pointers, no operation is performed and the function will return NULL.

yaslsplitlen

yastr * yaslsplitlen(const char * s, size_t len, const char * sep, size_t seplen, size_t * count)

The yaslsplitlen() function splits the given C string using the sep C string as the separator into an array of yastr strings. The count pointer is set to the number of arguments in the yastr array returned

This function is binary safe, which is why it requires the length of the string and separators, so both can contain binary data.

This function may return NULL on out of memory, or if a zero-length string or separator was given.

If the s, sep or count arguments to the yaslsplitlen() function are NULL pointers, no operation is performed and the function will return NULL.

Concatenation

This group contains all of the functions used to concatenate two strings together.

The functions in this section technically belongs to the modification group, but it was split out into its own group due to the large amount of functions.

yaslcat

yastr yaslcat(yastr s, const char * t)

The yaslcat() function appends the given C string to the yastr s

This function may realloc() the string so all references to the original yastr should be treated as invalid and should be replaced with the one returned by the function.

If the t argument to the yaslcat() function is a NULL pointer, no operation is performed and the function will return NULL.

yaslcatyasl

yastr yaslcatyasl(yastr s, const yastr t)

The yaslcat() function appends the given yastr t to the existing yastr s.

This function may realloc() the string so all references to the original yastr should be treated as invalid and should be replaced with the one returned by the function.

yaslcatlen

yastr yaslcatlen(yastr s, const void * t, size_t len)

The yaslcatlen() function appends the string t of length len to the end of the specified yastr.

This function is binary safe, which is why it requires the length of the string as an argument.

This function may realloc() the string so all references to the original yastr should be treated as invalid and should be replaced with the one returned by this function.

If the t argument to the yaslcatlen() function is a NULL pointer, no operation is performed and the function will return NULL.

yaslcatrepr

yastr yaslcatrepr(yastr s, const char * p, size_t len)

The yaslcatrepr() function takes a C string and appends an escaped string representation of it to the given yastr. All non-printable characters are turned into appropriate escape codes if existent, or a \x<hex> otherwise.

This function may realloc() the string so all references to the original yastr should be treated as invalid and should be replaced with the one returned by this function.

If the p argument to the yaslcatrepr() function is a NULL pointer, no operation is performed and the function will return NULL.

yaslcatvprintf

yastr yaslcatvprintf(yastr s, const char * fmt, va_list ap)

The yaslcatprintf() function appends a string obtained using a printf-like format specifier to the given yastr, taking an va_list argument instead of being a variadic function.

Often you need to create a new string with the printf-like format, and when this is needed you can just use yaslempty() as the target to create a new empty one.

This function may realloc() the string so all references to the original yastr should be treated as invalid and should be replaced with the one returned by this function.

If the fmt argument to the yaslcatvprintf() function is a NULL pointer, no operation is performed and the function will return NULL.

yaslcatprintf

yastr yaslcatprintf(yastr s, const char * fmt, ...)

The yaslcatprintf() function appends a string obtained using a printf-like format specifier to the given yastr.

Often you need to create a new string with the printf-like format, and when this is needed you can just use yaslempty() as the target to create a new empty one.

This function may realloc() the string so all references to the original yastr should be treated as invalid and should be replaced with the one returned by this function.

If the fmt argument to the yaslcatprintf() function is a NULL pointer, no operation is performed and the function will return NULL.

Examples
int a = 2, b = 2;
yastr string = yaslauto("Sum is: ");
string = yaslcatprintf(string, "%d + %d = %d", a, b, a + b);
printf("%s\n", string);

Will print Sum is: 2 + 2 = 4

Freeing

This group contains the functions used to free yastr strings.

yaslfree

void yaslfree(yastr s)

The yaslfree() function frees a yasl string.

yaslfreesplitres

void yaslfreesplitres(yastr * tokens, size_t count)

The yaslfreesplitres() function frees the result of yaslsplitlen().

If the given yastr * is NULL no operation is performed.

Low-level functions

This group contains the functions in the low-level API and should generally not be used in client code.

yaslAllocSize

size_t yaslAllocSize(yastr s)

The yaslAllocSize() function returns the total allocated size of the specified yasl string, including the yastrhdr and the full string buffer.

yaslheader

struct yastrhdr * yaslheader(const yastr s)

The yaslheader() function returns a pointer to the yastrhdr of a given yastr string.

yaslIncrLen

void yaslIncrLen(yastr s, size_t incr)

The yaslIncrLen() function increments the length and decrements the free space members in the yastrhdr of the given yastr by the amount given in incr, and also sets the new end of the string to NULL.

This function is used to fix the string length after calling yaslMakeRoomFor and then writing something to the end of the string.

Examples
size_t oldlen = yasllen(string);
string = yaslMakeRoomFor(string, BUFFER_SIZE);
nread = read(fd, string + oldlen, BUFFER_SIZE);
// ... check for nread <= 0 and handle it ...
yaslIncrLen(string, nread);

yaslMakeRoomFor

yastr yaslMakeRoomFor(yastr s, size_t addlen)

The yaslMakeRoomFor() function grows the free space at the end of the given yastr string so that the caller is sure that there is at least addlen bytes of space available at the end of the string.

This function does not update the len member of the string returned by yasllen() since it doesn’t change the length of the string, just the space available.

yaslRemoveFreeSpace

yastr yaslRemoveFreeSpace(yastr s)

The yaslRemoveFreeSpace() function realloc()‘s the string so that it has no free space at the end. The contained string will be changed, but the next concatenation operation will require an reallocation.

This function will realloc() the string so all references to the original yastr should be treated as invalid and should be replaced with the one returned by this function.

Changelog

Indices and tables