Citadel Source Code Documentation

libical

libical was originaly created by softwarestudio.org. It became used by a range of projects; after the upstream lost interest to continue maintaining libical, a couple of big projects started maintaining their bugfixes in forks of libical. After some more or less successful tries to find a new maintainer, Art managed to get in touch with the original author so we could revive the original http://freeassociation.sf.net project. Next effort was to merge in bugfixes from the various branches, and "get the band back together". Currently libical is maintained in a cooperative effort of the downstream projects and others.

libcitadel

libcitadel started out as a set of utilities used in several Citadel components. Meanwhile it contains some components that might be of use for others:

StrBuf

StrBuf is an elastic string class to handle strings in C more efficiently. Some of the issues with C strings that are addressed are:

• getting their length is expensive (strlen)
• managing their memory is complicated:
• most functions don't know about the buffer size, or if they can, can't readjust it by themselves
• if you manage memory too strictly, you have to alloc, memcpy & free a lot
• alloc / free doesn't scale well in multithreadded environemnts if invoked to frequently (at least with current glibc implementations), so doing less of them is a good thing.
• while strcat might look like a smart idea, its not. StrBuf commands with "Append" in their name start their work at the end of a current string, like strcat does. Flush it first, if you want it to be an empty string.
• StrBuf hides its inner workings from the caller. Think of them as being 'private' in a C++ object.

How?

StrBuf manages its memory by itself; it will double its size until everything fits in. StrBuf has a default buffer size, which you can set at the start of your application. There are also tools to evaluate such values (counting reallocs, slags pace on delete..) For not wasting memory nor doing to frequent reallocs, you can hint StrBuf for instances that are going to be extraordinary big by using NewStrBufPlain(NULL, );

StrBuf also has a bunch of string-Transcoding functions which will escape / transcode / de-escape contents for commonly used patterns, like Quoted-printable encoding, URL-encoding, XML/HTML encoding, gzip compression.

StrBufs are assumed to have ASCII or UTF-8 contents in many places; many other places don't care about the content, even pure binary data like images are no problem. Its up to you to treat it appropriate, or use for example the QP decoder with its internal iconv wrapper to get UTF-8.