% $Id: DYNSTR.TEX 1.1 2000/01/24 10:18:50 ska Exp ska $
\section{\label{ssDynstr}\subsys{dynstr}}

\subsection{Design}

This subsystem implements functions to work over dynamic strings, strings
that are held within dynamically allocated and size-adjusted buffers.
Usually they are represented by \fct{(char *)} pointers and the buffers
they point to are modified each time the contents has been changed.

To ease the programming process most of the functions are macros
actually, that automatically create pointers to the \fct{(char *)}
pointers in order to be able to reallocate the buffer. These functions
are not limited to the use as {\em dynamic strings}, but may be used
in conjunction with every other {\em dynamically} allocated buffer as well.

Most of the functions also imply that the pointer passed to the
functions already contains a valid pointer to a dynamically allocated
buffer or \fct{NULL}, if not. That means that all dynamic strings
(dynstrings), or better the pointer representing them, must be
pre-initialized by the constant \fct{NULL}.

\subsection{Implementation}

\subsubsection{Types}

\begin{tabTS}
\fct{STR\_SAVED\_TOKENS} & ANSI C specifies the function \fct{strtok},
	but it cannot reentrantly be called. This data type is used in conjuntion
	with the functions \fct{StrTokenize()}, \fct{StrTokSave()} and
	\fct{StrTokRestore()} to implement a reentrant \fct{strtok}. \\
\fct{STR\_QUOTES} & This data type is used to store which quotes the
	functions \fct{StrQuote()}, \fct{StrUnquote()} and associated ones
	shall support. The structure contains fields for word delimiters,
	characters to quote, single character quotes, pairily used quotes and
	unpairily used quotes. \\
\end{tabTS}

\subsubsection{Functions}

Most functions, that have a counterpart in the standard string
functions, are named equally, except that the first character (from
the \fct{str*()} or the \fct{mem*()} part) and the first
character of the actual function action are uppercased, e.g.
\fct{StrCpy} is related to \fct{strcpy}, but \fct{_fstrcpy} is
named \fct{_fStrCpy} within \suppl.\newline
\noindent Some functions are prefixed by an \fct{E}, too, e.g.
\fct{EStrConcat}, these functions work as the function without
the \fct{E}, but terminate the program with an "{}Out of memory"{}
error message on failure.

The recommended way to represent a dynstring is with the data type
\fct{dynstr}, though, it is a \fct{(char*)} bascally. These dynstrings
are passed to the functions and, if necessary, these functions
are actually macros that generate the address of the dynstring and
pass it to the real function. The use of dynstrings becomes more
transparent that way. However, mostly all functions take up to one
dynstring as parameter and tried all the rest as normal \fct{(char*)}
pointers. This way one can easily intermix normal C strings and
dynstrings with functions, even with the standard string functions.

The most advantage of these function over the standard string functions
is that the user need not worry about the size of the buffer the string
is located in, because the buffer is size-adjusted automatically. That also
means that the physical location of the string might change a lot. Also
they are robust against \fct{NULL} strings, that means that most of the
functions treat \fct{NULL} as an empty string.

Several functions have been included as well to keep the naming convention
as closed as possible, that means that there is also a \fct{StrCmp} function,
although the implementation does not change neither of the strings, so
no new function would be necessary. But those functions are actually
implemented as macros to the associated function of \subsys{sstr}, because
although they do not change the strings at all, they must be robust against
\fct{NULL} values.

\begin{tableThree}{name}%
{dyn\footnote{Takes a dynstring as first argument}}%
{purpose}
\fct{StrDup} & & Duplicates a string into the local heap. \\
\fct{StrChg} & X & Resize a dynstring. \\
\fct{StrFree} & X & Deallocate a dynstring and assign \fct{NULL} to the
	\fct{dynstr} pointer. \\
\fct{StrRepl} & X & Replaces one dynstring by another one. Both dynstrings
	point to the same physical memory after this operation. \\
\fct{StrConcat} & & Concats several strings together and returns the
	result as pointer to a dynamically allocated buffer. \\
\fct{StrTrim} & & Reallocates the passed-in string to allocate the only
	necessary amount of spaces. \\
\fct{StrChar} & & Creates a new, dynamically allocated  string containing
	one single character specified on call. \\
\fct{StrStrip} & & Removes any occurance of one character from the end
	of a string. \\
\fct{StrCpy} & & Copies a dynstring. This operation is equal to duplicate
	a string into the destination dynstring. \\
\fct{StrAppDelimStr} & X & Appends a new string to a dynstring and
	delimit it from the previous contents by a delimiter described
	in a \tok{STR\_QUOTES} structure, if necessary. \\
\fct{StrAppStr} & X & Appends a strings to a dynstring. \\
\fct{StrCat} & X & Appends a strings to a dynstring. \\
\fct{StrAppQStr} & X & Appends a string after quoting it to a dynstring
	and delimits it by a delimiter, if necessary. \\
\fct{StrAppChr} & X & Appends a single character to a dynstring. \\
\fct{StrQuote} & & Quotes a whole string, so that unquoting it reveals
	exactly the same string. Quotes already included within the string
	are interpreted as normal characters to be preserved within the
	string. \\
\fct{StrUnquote} & & Removes quotes from a string. If quotes are present
	within the result, they were quoted. \\
\fct{StrUnquoteTokenAppend} & X & Extracts the next token (delimited argument)
	from a string and appends it to a dynstring. \\
\fct{StrUnquoteToken} & X & Extracts the next token (delimited argument)
	from a string and assigns it to a dynstring. \\
\fct{StrTokenize} & & Reimplements the function \fct{strtok} and is, under
	some circumstances, reentrant and keeps the string unchanged.
	It is to be used in conjunction with the functions \fct{StrTokSave},
	\fct{StrTokRestore}, and \fct{StrTokStop}. \\
\fct{StrTokStop} & & Makes sure that a) function \fct{StrTokenize} returns
	\tok{NULL} next time, and b) that the string is restored to its
	original value. \\
\fct{StrTokSave} & & Saves all internally used data of the function
	\fct{StrTokenize}. When restored later, the function \fct{StrTokenize}
	can be nestably be used.\\
\fct{StrTokRestore} & & Restores the data saved by \fct{StrTokStore}. \\
\fct{StrLeft} & & Duplicates \tok{n} characters from the left of the
	passed-in string in a dynamically allocated buffer. \\
\fct{StrRight} & & Duplicates \tok{n} characters from the right of the
	passed-in string in a dynamically allocated buffer. \\
\fct{StrMiddle} & & Duplicates \tok{n} characters beginning at the
	specified position of the passed-in string in a dynamically
	allocated buffer. \\
\fct{StrTail} & & Duplicates all characters to the right of the specified
	position of the passed-in string in a dynamically allocated buffer. \\
\fct{StrBeg} & & Tests if two strings begins with the same sequence
	of characters. \\
\fct{StrCString} & & Interprete a C-style ASCIIZ string into its
	binary format, e.g. mapping the sequence \tok{"{}\\n"{}} to
	the character with the ASCII value 10 (ten). The transformed
	string overwrites the passed-in string. \\
\fct{StrWord} & & Removes any leading and trailing whitespaces and
	reallocates the string to allocate the minimum necessary space. \\
\fct{StrChr} & & Searches for the first occurence of a character in
	a string. \\
\fct{StrnLen} & & Returns the length of the string, but ensures to
	break after \tok{n} bytes. \\
\fct{StrDupe} & & Duplicates a portion of a string into the heap. \\
\fct{StrEnd} & & Returns a pointer to the NUL-terminator byte of the string. \\
\end{tableThree}

