From 8ae60f848d549c4506498dbecded6f539a6d88c7 Mon Sep 17 00:00:00 2001 From: jthorn Date: Wed, 4 Jun 2003 12:21:10 +0000 Subject: document that key-value table routines now have Fortran wrappers git-svn-id: http://svn.cactuscode.org/flesh/trunk@3229 17b73243-c579-4c4c-a9d2-2d5706c11dac --- doc/UsersGuide/FunctionReference.tex | 321 ++++++++++++++++++++++++++++++++++- doc/UsersGuide/UtilityRoutines.tex | 7 +- 2 files changed, 316 insertions(+), 12 deletions(-) (limited to 'doc/UsersGuide') diff --git a/doc/UsersGuide/FunctionReference.tex b/doc/UsersGuide/FunctionReference.tex index e280bb15..085df257 100644 --- a/doc/UsersGuide/FunctionReference.tex +++ b/doc/UsersGuide/FunctionReference.tex @@ -3116,7 +3116,11 @@ Older API to interpolate a list of processor-local arrays. The following list of error codes indicates specific error conditions. For the complete list of possible error return codes you should refer to the ThornGuide's chapter of the -corresponding interpolation thorn(s) you are using. +corresponding interpolation thorn(s) you are using. To find the numerical +values of the error codes (or more commonly, to find which error code +corresponds to a given numerical value), look in the files +\verb|cctk_Interp.h|, \verb|util_ErrorCodes.h|, and/or \verb|util_Table.h| +in the \verb|src/include/| directory in the Cactus flesh. \end{Error} \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE} one or more of the interpolation points is out of range @@ -3666,6 +3670,13 @@ A negative return code indicates an error condition: %notyet \end{SeeAlsoSection} %notyet %notyet \begin{ErrorSection} +%notyet \begin{Error}{} +%notyet To find the numerical +%notyet values of the error codes (or more commonly, to find which error code +%notyet corresponds to a given numerical value), look in the files +%notyet \verb|cctk_Interp.h|, \verb|util_ErrorCodes.h|, and/or \verb|util_Table.h| +in the \verb|src/include/| directory in the Cactus flesh. +%notyet \end{Error} %notyet \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE} %notyet one or more of the interpolation points is out of range %notyet (in this case additional information about the out-of-range point @@ -3956,6 +3967,13 @@ with non-uniformly spaced data points. \end{SeeAlsoSection} \begin{ErrorSection} +\begin{Error}{} +To find the numerical +values of the error codes (or more commonly, to find which error code +corresponds to a given numerical value), look in the files +\verb|cctk_Interp.h|, \verb|util_ErrorCodes.h|, and/or \verb|util_Table.h| +in the \verb|src/include/| directory in the Cactus flesh. +\end{Error} \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE} one or more of the interpolation points is out of range (in this case additional information about the out-of-range point @@ -4284,6 +4302,13 @@ if (CCTK_InterpLocalUniform(N_DIMS, %notyet \end{SeeAlsoSection} %notyet %notyet \begin{ErrorSection} +%notyet \begin{Error}{} +%notyet To find the numerical +%notyet values of the error codes (or more commonly, to find which error code +%notyet corresponds to a given numerical value), look in the files +%notyet \verb|cctk_Interp.h|, \verb|util_ErrorCodes.h|, and/or \verb|util_Table.h| +in the \verb|src/include/| directory in the Cactus flesh. +%notyet \end{Error} %notyet \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE} %notyet one or more of the interpolation points is out of range %notyet (in this case additional information about the out-of-range point @@ -6292,7 +6317,14 @@ many are C-only. \section{Functions Alphabetically} -\begin{Lentry} +Here the functions are listed alphabetically within each section. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%% comment this whole section out until it's non-empty +%%\subsection{Miscellaneous Functions} +%% +%%\begin{Lentry} %%\item[Util\_asprintf] %% [\pageref{Util-asprintf}] @@ -6387,12 +6419,6 @@ many are C-only. %%\item[Util\_SplitString] %% [\pageref{Util-SplitString}] -%%\item[Util\_StrCmpi] -%% [\pageref{Util-StrCmpi}] - -%%\item[Util\_Strdup] -%% [\pageref{Util-Strdup}] - %%\item[Util\_StringListAdd] %% [\pageref{Util-StringListAdd}] @@ -6405,6 +6431,23 @@ many are C-only. %%\item[Util\_StringListNext] %% [\pageref{Util-StringListNext}] +%%\end{Lentry} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{String Functions} + +\begin{Lentry} + +\item[Util\_StrCmpi] + [\pageref{Util-StrCmpi}] +Compare two strings, ignoring upper/lower case. + +\item[Util\_Strdup] + [\pageref{Util-Strdup}] +``Duplicate'' a string, +\ie{} copy it to a newly--\verb|malloc|ed buffer. + \item[Util\_Strlcat] [\pageref{Util-Strlcat}] Concatenate two strings safely. @@ -6413,6 +6456,14 @@ Concatenate two strings safely. [\pageref{Util-Strlcpy}] Copy a string safely. +\end{Lentry} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Table Functions} + +\begin{Lentry} + \item[Util\_TableClone] [\pageref{Util-TableClone}] Create a new table which is a ``clone'' (exact copy) of an existing @@ -6570,6 +6621,235 @@ a copy of a specified C-style null-terminated character string %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\begin{FunctionDescription}{Util\_StrCmpi} +\label{Util-StrCmpi} +Compare two strings, ignoring upper/lower case. + +\begin{SynopsisSection} +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_String.h" +int cmp = Util_StrCmpi(const char *str1, const char *str2); +\end{verbatim} +\end{Synopsis} +\end{SynopsisSection} + +\begin{ResultSection} +\begin{Result}{cmp} +An integer which is:\\ +\begin{tabular}{@{}rl} +$<0$ & if $\verb|str1| < \verb|str2|$ in lexicographic order + ignoring upper/lower case distinctions \\ +$0$ & if $\verb|str1| = \verb|str2|$ + ignoring upper/lower case distinctions \\ +$>0$ & if $\verb|str1| > \verb|str2|$ in lexicographic order + ignoring upper/lower case distinctions %%%\\ +\end{tabular} +\end{Result} +\end{ResultSection} + +\begin{ParameterSection} +\begin{Parameter}{str1} +A non-NULL pointer to a (C-style NUL-terminated) string to be compared. +\end{Parameter} +\begin{Parameter}{str2} +A non-NULL pointer to a (C-style NUL-terminated) string to be compared. +\end{Parameter} +\end{ParameterSection} + +\begin{Discussion} +The standard C library \verb|strcmp()| function does a {\em case-sensitive\/} +string comparison, \ie{} \verb|strcmp("cactus", "Cactus")| will find the +two strings not equal. Sometimes it's useful to do {\em case-insensitive\/} +string comparison, where upper/lower case distinctions are ignored. +Many systems provide a \verb|strcasecmp()| or \verb|strcmpi()| +function to do this, but some systems don't, and even on those that do, +the name isn't standardised. So, Cactus provides its own version, +\verb|Util_StrCmpi()|. + +Notice that the return value of \verb|Util_StrCmpi()|, like that of +\verb|strcmp()|, is zero (logical ``false'' in C) for equal strings, +and nonzero (logcla ``true'' in C) for non-equal strings. +Code of the form +\begin{verbatim} +if (Util_StrCmpi(str1, str2)) + { /* strings differ */ } +\end{verbatim} +or +\begin{verbatim} +if (!Util_StrCmpi(str1, str2)) + { /* strings are identical apart from case distinctions */ } +\end{verbatim} +may be confusing to readers, because the sense of the comparison +isn't immediately obvious. Writing an explicit comparison against zero +make make things clearer: +\begin{verbatim} +if (Util_StrCmpi(str1, str2) != 0) + { /* strings differ */ } +\end{verbatim} +or +\begin{verbatim} +if (Util_StrCmpi(str1, str2) == 0) + { /* strings are identical apart from case distinctions */ } +\end{verbatim} + +Unfortunately, the basic concept of ``case-insensitive'' string +operations doesn't generalize well to non-English character sets,%%% +\footnote{%%% + Hawaiian and Swahili are apparently the only + other living languages that use solely the + 26-letter ``English'' Latin alphabet. + }%%% +{} where lower-case $\leftrightarrow$ upper-case mappings may be +context-dependent, many-to-one, and/or time-dependent.%%% +\footnote{%%% + For example, the (lower-case) German ``\ss'' + doesn't have a unique upper-case equivalent: + ``\ss'' usually maps to ``SS'' + (for example ``gro\ss'' $\leftrightarrow$ ``GROSS''), + {\em but\/} if that would conflict + with another word, then ``\ss'' maps to ``SZ'' + (for example ``ma\ss{}e'' $\leftrightarrow$ ``MASZE'' + because there's a different word ``MASSE''). + Or at least that's the way it was prior to 1998. + The 1998 revisions to German orthography + removed the SZ rule, so now (post-1998) the two + distinct German words ``masse'' (English ``mass'') + and ``ma\ss{}e'' (``measures'') have identical + upper-case forms ``MASSE''. To further complicate + matters, (the German-speaking parts of) Switzerland + have a slightly different orthography, which never + had the SZ rule. + + French provides another tricky example: + In France ``\'e'' $\leftrightarrow$ ``\'E'' and + ``\`e'' $\leftrightarrow$ ``\`E'', + whereas in (the French-speaking parts of) Canada + there are no accents on upper-case letters, so + ``\'e'' $\leftrightarrow$ ``E'' and + ``\`e'' $\leftrightarrow$ ``E''. + }%%% +{} At present Cactus basically ignores these issues. :( +\end{Discussion} + +\begin{SeeAlsoSection} +\begin{SeeAlso}{strcmp()} +Standard C library function (prototype in \verb||) +to compare two strings. +\end{SeeAlso} +\end{SeeAlsoSection} + +\begin{ExampleSection} +\begin{Example}{C} +\begin{verbatim} +#include "util_String.h" + +/* does the Cactus parameter driver specify the PUGH driver? */ +/* (Cactus parameters are supposed to be case-insensitive) */ +if (Util_StrCmpi(driver, "pugh") == 0) + { /* PUGH code */ } +else + { /* non-PUGH code */ } +\end{verbatim} +\end{Example} +\end{ExampleSection} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_Strdup} +\label{Util-Strdup} +``Duplicate'' a string, \ie{} copy it to a newly--\verb|malloc|ed buffer. + +\begin{SynopsisSection} +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_String.h" +char* copy = Util_Strdup(const char *str); +\end{verbatim} +\end{Synopsis} +\end{SynopsisSection} + +\begin{ResultSection} +\begin{Result}{copy} +A pointer to a buffer obtained from \verb|malloc()|, +which this function sets to a copy of the (C-style NUL-terminated) +string \verb|str|. This buffer should be freed with \verb|free()| +when it's not needed any more. +\end{Result} +\end{ResultSection} + +\begin{ParameterSection} +\begin{Parameter}{str} +A non-NULL pointer to a (C-style NUL-terminated) string. +\end{Parameter} +\end{ParameterSection} + +\begin{Discussion} +Many systems have a C library function \verb|strdup|, which +\verb|malloc|s sufficient memory for a copy of its argument string, +does the copy, and returns a pointer to the copy. However, some +systems lack this function, so Cactus provides its own version, +\verb|Util_Strdup()|. +\end{Discussion} + +\begin{SeeAlsoSection} +\begin{SeeAlso}{} +System header file containing prototypes for +\verb|malloc()| and \verb|free()|. +\end{SeeAlso} +\begin{SeeAlso}{strcpy()} +Standard C library function (prototype in \verb||) +to copy a string to a buffer. +{\em This does not check that the buffer is big enough to hold the string, +and is thus very dangerous. Use \verb|Util_Strlcpy()| instead!} +\end{SeeAlso} +\begin{SeeAlso}{Util\_Strlcpy()} +Safely copy a string. +\end{SeeAlso} +\end{SeeAlsoSection} + +\begin{ErrorSection} +\begin{Error}{NULL} +\verb|malloc()| was unable to allocate memory for the buffer. +\end{Error} +\end{ErrorSection} + +\begin{ExampleSection} +\begin{Example}{C} +\begin{verbatim} +#include "util_String.h" + +/* + * return the (positive) answer to a question, + * or negative if an error occured + */ +int answer_question(const char* question) +{ +/* + * we need to modify the question string in the process of parsing it + * but we must not destroy the input ==> copy it and modify the copy + * + * ... note the const qualifier on question_copy says that + * the pointer question_copy won't itself change, but + * we can modify the string that it points to + */ +char* const question_copy = Util_Strdup(question); +if (question_copy == NULL) + { return -1; } /* couldn't get memory for copy buffer */ + +/* code that will modify question_copy */ + +free(question_copy); +return 42; +} +\end{verbatim} +\end{Example} +\end{ExampleSection} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \begin{FunctionDescription}{Util\_Strlcat} \label{Util-Strlcat} Concatenate strings safely. @@ -6635,6 +6915,12 @@ destination buffer), and it always leaves \verb|dst| string NUL-terminated. \end{Discussion} \begin{SeeAlsoSection} +\begin{SeeAlso}{strcat()} +Standard C library function (prototype in \verb||) +to concatenate two strings. +{\em This does not check that the buffer is big enough to hold the result, +and is thus very dangerous. Use \verb|Util_Strlcat()| instead!} +\end{SeeAlso} \begin{SeeAlso}{Util\_Strlcpy()} Safely copy a string. \end{SeeAlso} @@ -6762,6 +7048,15 @@ the end of the destination buffer with NUL characters. \end{Discussion} \begin{SeeAlsoSection} +\begin{SeeAlso}{strcpy()} +Standard C library function (prototype in \verb||) +to copy a string to a buffer. +{\em This does not check that the buffer is big enough to hold the string, +and is thus very dangerous. Use \verb|Util_Strlcpy()| instead!} +\end{SeeAlso} +\begin{SeeAlso}{Util\_Strdup()} +``Duplicate'' a string, \ie{} copy it to a newly-\verb|malloc|ed buffer. +\end{SeeAlso} \begin{SeeAlso}{Util\_Strlcat()} Safely concatenates two strings. \end{SeeAlso} @@ -7007,6 +7302,9 @@ in \verb|"util_Table.h"|: \end{Discussion} \begin{SeeAlsoSection} +\begin{SeeAlso}{Util\_StrCmpi()} +compare two strings, ignoring upper/lower case +\end{SeeAlso} \begin{SeeAlso}{Util\_TableClone()} create a new table which is a ``clone'' (exact copy) of an existing table @@ -8995,6 +9293,11 @@ handle to the table \end{Parameter} \end{ParameterSection} +\begin{Discussion} +See \verb|Util_TableCreate()| for further discussion of the semantics +of flag words. +\end{Discussion} + \begin{SeeAlsoSection} \begin{SeeAlso}{Util\_TableClone()} create a new table which is a ``clone'' (exact copy) of an existing @@ -9028,7 +9331,7 @@ handle is invalid /* case-sensitive/insensitive semantics as a certain table uses */ int compare_strings(int handle, const char *str1, const char *str2) { -int flags = Util_TableQueryFlags(int handle); +int flags = Util_TableQueryFlags(handle); return (flags & UTIL_TABLE_FLAGS_CASE_INSENSITIVE) ? Util_StrCmpi(str1, str2) : strcmp (str1, str2); diff --git a/doc/UsersGuide/UtilityRoutines.tex b/doc/UsersGuide/UtilityRoutines.tex index e8a8e2b4..9a65a78a 100644 --- a/doc/UsersGuide/UtilityRoutines.tex +++ b/doc/UsersGuide/UtilityRoutines.tex @@ -108,9 +108,10 @@ of the possible bit flags and their semantics. Here's a simple example (in C)%%% \footnote{%%% - In theory tables should be usable from both - C and Fortran, but noone has written the Fortran - wrappers yet, so at present tables are C-only. + All (or almost all) of the table routines + are also usable from Fortran. See the full + descriptions in section~\ref{sect-FunctionReference/UtilityFunctions} + for details. }%%% {} of how to use a table: \begin{verbatim} -- cgit v1.2.3