@deffn Typedef filament
@fnindex filament

Opaque data type used to hold 8-bit clean dynamic strings which know
their own length and resize themselves to avoid buffer overruns.

@end deffn

@deftypefn Function filament* filnew (const char *const i@var{init}, size_t l@var{len})
@fnindex filnew


Create a new filament object, initialised to hold a copy of the
first @var{len} bytes starting at address @var{init}.  If @var{init} is NULL, or
@var{len} is 0 (or less), then the initialised filament will return the
empty string, "", if its value is queried.


A newly created filament object is returned.

@end deftypefn

@deftypefn Function char* ffildelete (ffilament *f@var{fil})
@fnindex fildelete


The memory being used by @var{fil} is recycled.


The original contents of @var{fil} are converted to a null terminated
string which is returned, either to be freed itself or else used
as a normal C string.  The entire filament contents are copied into
this string including any embedded nulls.

@end deftypefn

@deftypefn Function ffilament* ffiliinit (ffilament *f@var{fil}, const char *const i@var{init}, size_t l@var{len})
@fnindex filinit


Initialise a filament object to hold a copy of the first @var{len} bytes
starting at address @var{init}.  If @var{init} is NULL, or @var{len} is 0 (or less),
then the filament will be reset to hold the empty string, "".


The initialised filament object is returned.

@end deftypefn

@deftypefn Function char* ffilval (ffilament *f@var{fil})
@fnindex filval



A pointer to the internal null terminated string held by the filament
object is returned.  Since the @var{fil} may contain embedded nulls, it
is not entirely safe to use the @code{strfoo()} API to examine the contents
of the return value.

@end deftypefn

@deftypefn Function size_t ffillen (ffilament *f@var{fil})
@fnindex fillen



The length of @var{fil}, including any embedded nulls, but excluding the
terminating null, is returned.

@end deftypefn

@deftypefn Function innt ffilelt (ffilamennt *f@var{fil}, size_t n@var{n})
@fnindex filelt


This function looks for the @var{n}'th element of @var{fil}.


If @var{n} is an index inside the filament @var{fil}, then the character stored
at that index cast to an int is returned, otherwise @var{n} is outside
this range and -1 is returned.

@end deftypefn

@deftypefn Function char* ffilcat (ffilament *f@var{fil}, const char *s@var{str})
@fnindex filcat


The bytes starting at address @var{str} upto and including the first null
byte encountered are destructively concatenated to @var{fil}.  If
necessary @var{fil} is dynamically reallocated to make room for this
operation.


A pointer to the null terminated string (along with any embedded nulls)
which is the result of this concatenation is returned.

@end deftypefn

@deftypefn Function char* ffilnncat (ffilamennt *f@var{fil}, connst char *s@var{str}, size_t n@var{n})
@fnindex filncat


@var{n} bytes starting with the byte at address @var{str} are destructively
concatenated to @var{fil}.  If necessary, @var{fil} is dynamically reallocated
to make room for this operation.


A pointer to the null terminated string (along with any embedded nulls)
which is the result of this concatenation is returned.

@end deftypefn

@deftypefn Function cchar* ffilccccat (ffilament *f@var{fil}, int c@var{c})
@fnindex filccat


@var{c} is destructively concatenated to @var{fil}.  If necessary, @var{fil} is
dynamically reallocated to make room for this operation.  When used
repeatedly this function is considerably less efficient than @code{filncat()},
since it must maintain the '\0' suffix for C string compatibility
after every appended character, and then overwrite that '\0' on the
next call.


A pointer to the null terminated string (along with any embedded nulls)
which is the result of this concatenation is returned.

@end deftypefn

