Initial revision

doc/programmer/stringdict.tex

@@ -0,0 +1,91 @@
+\subsection{Dictionary}
+This is just a simple implementation of an dictionary of name value strings
+on top of the LLD linked list package. It is needed in the histogram memory
+module and several other places. This module provides the following functions:
+
+\begin{flushleft} \small
+\begin{minipage}{\linewidth} \label{scrap1}
+$\langle$Protos {\footnotesize ?}$\rangle\equiv$
+\vspace{-1ex}
+\begin{list}{}{} \item
+\mbox{}\verb@@\\
+\mbox{}\verb@  pStringDict CreateStringDict(void);@\\
+\mbox{}\verb@  void        DeleteStringDict(pStringDict self);@\\
+\mbox{}\verb@@\\
+\mbox{}\verb@  int StringDictAddPair(pStringDict self, char *name, char *value);@\\
+\mbox{}\verb@  int StringDictExists(pStringDict self, char *name);@\\
+\mbox{}\verb@  int StringDictUpdate(pStringDict self, char *name, char *value);@\\
+\mbox{}\verb@  int StringDictGet(pStringDict self, char *name, char *pResult, int iLen);@\\
+\mbox{}\verb@  int StringDictGetAsNumber(pStringDict self, char *name, float *fVal);@\\
+\mbox{}\verb@  int StringDictDelete(pStringDict self, char *name);@\\
+\mbox{}\verb@@\\
+\mbox{}\verb@  const char *StringDictGetNext(pStringDict self, @\\
+\mbox{}\verb@                                char *pValue, int iValLen);@\\
+\mbox{}\verb@  void StringDictKillScan(pStringDict self);@\\
+\mbox{}\verb@@$\diamond$
+\end{list}
+\vspace{-1ex}
+\footnotesize\addtolength{\baselineskip}{-1ex}
+\begin{list}{}{\setlength{\itemsep}{-\parsep}\setlength{\itemindent}{-\leftmargin}}
+\item Macro referenced in scrap ?.
+\end{list}
+\end{minipage}\\[4ex]
+\end{flushleft}
+As usual, all function return 1 on success, 0 if there is a problem.
+
+CreateStringDict creates and initialises a new string dictionanry.
+
+DeleteStringDict deletes the whole dictionary and all ist values from
+memory. self will point to rubbish afterwards.
+
+StringDictAddPair adds a new name value pair to the dictionary.
+
+StringDictExists test for the existence of name in the Dictionary.
+
+StringDictUpdate replaces the value for name with the new one specified.
+
+StringDictGet copies the value for name into the string pResult, but maximum
+iLen characters. If pResult is NULL, this function returns the length of the
+value string.
+
+StringDictDelete deletes the entry for name from the dictionary.
+
+StringDictGetNext implements a scan through the whole dictionary. It returns
+a pointer to the current key or NULL if the dictionary is exhausted. 
+Maximum iValLen characters of value information will be copied into pValue.
+NEVER, ever delete the pointer passed from StringDictGetNext. A core dump
+will be your reward. Please note, that each call to the usual search
+functions will mess up a dictionary traversal. 
+
+StringDictKillScan clears the scan flag in a way that a new one is done
+ with the next call to StringDictGetNext. 
+
+\begin{flushleft} \small
+\begin{minipage}{\linewidth} \label{scrap2}
+\verb@"stringdict.h"@ {\footnotesize ? }$\equiv$
+\vspace{-1ex}
+\begin{list}{}{} \item
+\mbox{}\verb@@\\
+\mbox{}\verb@/*--------------------------------------------------------------------------@\\
+\mbox{}\verb@                        S T R I N G D I C T@\\
+\mbox{}\verb@@\\
+\mbox{}\verb@ A module which implements a general purpose string dictionary.@\\
+\mbox{}\verb@@\\
+\mbox{}\verb@ copyright: see implementation file@\\
+\mbox{}\verb@@\\
+\mbox{}\verb@ Mark Koennecke, April 1997@\\
+\mbox{}\verb@---------------------------------------------------------------------------*/@\\
+\mbox{}\verb@#ifndef SICSSTRINGDICT@\\
+\mbox{}\verb@#define SICSSTRINGDICT@\\
+\mbox{}\verb@@\\
+\mbox{}\verb@  typedef struct __StringDict *pStringDict;@\\
+\mbox{}\verb@@\\
+\mbox{}\verb@@$\langle$Protos {\footnotesize ?}$\rangle$\verb@@\\
+\mbox{}\verb@@\\
+\mbox{}\verb@#endif@\\
+\mbox{}\verb@@\\
+\mbox{}\verb@@$\diamond$
+\end{list}
+\vspace{-2ex}
+\end{minipage}\\[4ex]
+\end{flushleft}