ustr 1.0.1

ustr (Micro string library) is a string API for C. A few years ago now I wrote a very extensive String API for C, called Vstr, it was designed to perform extremely well for IO like patterns as that was my planned usage (for instance And-httpd, my Web server). It works very well, for that usage.
Also due to the extensivness of the API I basically used it everywhere, even though there are some things it is somewhat "overkill" for, and I wanted other people to use it so I didnt have to resort to using string.h when creating patches for their code. However more than a few C coders I speak to have one of a few reasons why they dont want to use Vstr. The ustr API should solve all of these problems, and hopefully fill in all the gaps where Vstr is the 500lb hammer.
A Significant example of usage, with comments:
Ustr *s1 = USTR(""); /* == "", always works */
Ustr *s2 = ustr_dup(s1); /* == "", always works */
Ustr *s3 = ustr_dup_cstr(""); /* == "", always works */
ustr_cmp_eq(s1, s2); /* == TRUE */
ustr_cmp_eq(s1, s3); /* == TRUE */
if (ustr_shared(s2)) /* This is TRUE, as a constant/read-only string cannot be freed */
/* whatever */ ;
if (ustr_ro(s2)) /* This is TRUE */
/* whatever */ ;
if (!ustr_add_fmt(&s2, "%s %d %c%d", "x", 4, 0, 8))
/* error */ ;
if (ustr_owner(s1)) /* This will return FALSE, as noone owns the "" read-only string */
/* whatever */ ;
if (ustr_owner(s2)) /* This will return TRUE, as weve now got allocated memory for s2 */
/* whatever */ ;
foo_API(ustr_cstr(s1), ustr_len(s1)); /* == "", 0 */
foo_API(ustr_cstr(s2), ustr_len(s2)); /* == "x 4 008", 6 */
s3 = ustr_dup(s2); /* dont need to free s3 as its empty */
/* dont need to check for errors as s2 == s3 */
if (ustr_owner(s2)) /* This will now return FALSE, weve got two references: s2 and s3 */
/* whatever */ ;
if (ustr_shared(s2)) /* This is FALSE, its a non-shared string referenced by both s2 and s3 */
/* whatever */ ;
ustr_free(s2); /* freed one reference to the data pointed to by both s2 and s3 */
ustr_set_share(s2); /* Make s2/s3 "shared" data,
so it always has infinite references */
if (ustr_shared(s2)) /* This is TRUE */
/* whatever */ ;
if (ustr_ro(s2)) /* This is FALSE */
/* whatever */ ;
s3 = ustr_dup(s2); /* This is the same as s3 = s2; */
ustr_free(s2); /* These do nothing */
ustr_free(s2);
ustr_free(s2);
ustr_free(s2);
if (!ustr_add_cstr(&s3, "abcd"))
/* error */ ;
ustr_add_cstr(&s3, "1234");
ustr_add_cstr(&s3, "xyz");
if (ustr_enomem(s3)) /* check for errors on the last 2 ustr_add_cstr() functions at once
ustr_owner(x) has to be true for this to be reliable,
hence the explicit first check */
/* error */ ;
ustr_set_owner(s2); /* Make s2 be "non-shared" and have a single owner */
ustr_set_owner(s1); /* This fails, as you cant make a read-only string be "non-shared" */
ustr_sc_del(&s2); /* freed s2 and set s2 = USTR("") */
ustr_cmp_eq(s1, s2); /* == TRUE */
s2 = USTR1(x0b, "Hello world"); /* Constant string with data */
if (ustr_shared(s2)) /* This is TRUE */
/* whatever */ ;
if (ustr_ro(s2)) /* This is TRUE */
/* whatever */ ;
/* dont need to "free" anything else */
Enhancements:
- A lot of new functions were added, such as insert, replace, split, substitute, and io_getdelim.
- Documentation improvements were made.
- Build fixes were made for Win32.