diff options
Diffstat (limited to 'doc/UsersGuide/FunctionReference.tex')
-rw-r--r-- | doc/UsersGuide/FunctionReference.tex | 2461 |
1 files changed, 2259 insertions, 202 deletions
diff --git a/doc/UsersGuide/FunctionReference.tex b/doc/UsersGuide/FunctionReference.tex index c8a6b0ac..abd9fba9 100644 --- a/doc/UsersGuide/FunctionReference.tex +++ b/doc/UsersGuide/FunctionReference.tex @@ -6,410 +6,424 @@ % Function Reference for the Cactus User's Guide % @enddesc % @version $Header$ +% @history +% @date Sat Nov 3 18:47:53 MET 2001 +% @author Jonathan Thornburg <jthorn@aei.mpg.de> +% @desc Add new section for Utility functions, +% add key/value table functions in that section +% @endhistory % @@*/ \begin{cactuspart}{4}{FunctionReference}{$RCSfile$}{$Revision$} \renewcommand{\thepage}{\Alph{part}\arabic{page}} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \chapter{Cactus Functions} -In this section all Cactus functions are described. These functions are -callable from Fortran or C thorns. Note that whereas all functions are -available from C, not all are currently available from Fortran. +In this section all \hbox{{\tt CCTK\_}*} Cactus functions are described. +These functions are callable from Fortran or C thorns. Note that whereas +all functions are available from C, not all are currently available +from Fortran. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Functions Alphabetically} \begin{Lentry} \item[CCTK\_Abort] - [\pageref{Abort}] + [\pageref{CCTK-Abort}] \item[CCTK\_ArrayGroupSize] - [\pageref{ArrayGroupSize}] + [\pageref{CCTK-ArrayGroupSize}] Give the size of the variables in a group, from the name \item[CCTK\_ArrayGroupSizeB] - [\pageref{ArrayGroupSizeB}] + [\pageref{CCTK-ArrayGroupSizeB}] Give the size of the variables in a group, from either the name of the index \item[CCTK\_ArrayGroupSizeI] - [\pageref{ArrayGroupSizeI}] + [\pageref{CCTK-ArrayGroupSizeI}] Give the size of the variables in a group, from the group index \item[CCTK\_Barrier] - [\pageref{Barrier}] + [\pageref{CCTK-Barrier}] \item[CCTK\_Cmplx] - [\pageref{Cmplx}] + [\pageref{CCTK-Cmplx}] Turns two real numbers into a complex number (only C) \item[CCTK\_CmplxAbs] - [\pageref{CmplxAbs}] + [\pageref{CCTK-CmplxAbs}] Returns the absolute value of a complex number (only C) \item[CCTK\_CmplxAdd] - [\pageref{CmplxAdd}] + [\pageref{CCTK-CmplxAdd}] Returns the sum of two complex numbers (only C) \item[CCTK\_CmplxConjg] - [\pageref{CmplxConjg}] + [\pageref{CCTK-CmplxConjg}] Returns the complex conjugate of a complex number (only C) \item[CCTK\_CmplxCos] - [\pageref{CmplxCos}] + [\pageref{CCTK-CmplxCos}] Returns the Cosine of a complex number (only C) [not yet available] \item[CCTK\_CmplxDiv] - [\pageref{CmplxDiv}] + [\pageref{CCTK-CmplxDiv}] Returns the division of two complex numbers (only C) \item[CCTK\_CmplxExp] - [\pageref{CmplxExp}] + [\pageref{CCTK-CmplxExp}] Returns the Exponentiation of a complex number (only C) [not yet available] \item[CCTK\_CmplxImag] - [\pageref{CmplxImag}] + [\pageref{CCTK-CmplxImag}] Returns the imaginary part of a complex number (only C) \item[CCTK\_CmplxLog] - [\pageref{CmplxLog}] + [\pageref{CCTK-CmplxLog}] Returns the Logarithm of a complex number (only C) [not yet available] \item[CCTK\_CmplxMul] - [\pageref{CmplxMul}] + [\pageref{CCTK-CmplxMul}] Returns the multiplication of two complex numbers (only C) \item[CCTK\_CmplxReal] - [\pageref{CmplxReal}] + [\pageref{CCTK-CmplxReal}] Returns the real part of a complex number (only C) \item[CCTK\_CmplxSin] - [\pageref{CmplxSin}] + [\pageref{CCTK-CmplxSin}] Returns the Sine of a complex number (only C) [not yet available] \item[CCTK\_CmplxSub] - [\pageref{CmplxSub}] + [\pageref{CCTK-CmplxSub}] Returns the subtraction of two complex numbers (only C) \item[CCTK\_CmplxSqrt] - [\pageref{CmplxSqrt}] + [\pageref{CCTK-CmplxSqrt}] Returns the square root of a complex number (only C) [not yet available] \item[CCTK\_CoordDir] - [\pageref{CoordDir}] + [\pageref{CCTK-CoordDir}] Give the direction for a given coordinate name. \item[CCTK\_CoordIndex] - [\pageref{CoordIndex}] + [\pageref{CCTK-CoordIndex}] Give the grid variable index for a given coordinate. \item[CCTK\_CoordRange] - [\pageref{CoordRange}] + [\pageref{CCTK-CoordRange}] Return the global upper and lower bounds for a given coordinate name on a cctkGH \item[CCTK\_CoordRegisterData] - [\pageref{CoordRegisterData}] + [\pageref{CCTK-CoordRegisterData}] Register a coordinate as belonging to a coordinate system, with a given name and direction, and optionally with a grid variable \item[CCTK\_CoordRegisterRange] - [\pageref{CoordRegisterRange}] + [\pageref{CCTK-CoordRegisterRange}] Saves the global upper and lower bounds for a given coordinate name on a cctkGH \item[CCTK\_CoordRegisterSystem] - [\pageref{CoordRegisterSystem}] + [\pageref{CCTK-CoordRegisterSystem}] Registers a coordinate system with a given dimension \item[CCTK\_CoordSystemDim] - [\pageref{CoordDim}] + [\pageref{CCTK-CoordDim}] Provides the dimension of a given coordinate system \item[CCTK\_CoordSystemHandle] - [\pageref{CoordSystemHandle}] + [\pageref{CCTK-CoordSystemHandle}] Get the handle associated with a registered coordinate system \item[CCTK\_CoordSystemName] - [\pageref{CoordSystemName}] + [\pageref{CCTK-CoordSystemName}] Provides the name of the coordinate system identified by its handle \item[CCTK\_CreateDirectory] - [\pageref{CreateDirectory}] + [\pageref{CCTK-CreateDirectory}] Creates a directory \item[CCTK\_DecomposeName] - [\pageref{DecomposeName}] + [\pageref{CCTK-DecomposeName}] Given the full name of a variable/group, separates the name returning both the implementation and the variable/group \item[CCTK\_DisableGroupComm] - [\pageref{DisableGroupComm}] + [\pageref{CCTK-DisableGroupComm}] Disable the communication for a group \item[CCTK\_DisableGroupStorage] - [\pageref{DisableGroupStorage}] + [\pageref{CCTK-DisableGroupStorage}] Disable the storage for a group \item[CCTK\_EnableGroupComm] - [\pageref{EnableGroupComm}] + [\pageref{CCTK-EnableGroupComm}] Enable the communication for a group \item[CCTK\_EnableGroupStorage] - [\pageref{EnableGroupStorage}] + [\pageref{CCTK-EnableGroupStorage}] Enable the storage for a group \item[CCTK\_Equals] - [\pageref{Equals}] + [\pageref{CCTK-Equals}] Check for equality of strings \item[CCTK\_Exit] - [\pageref{Equals}] + [\pageref{CCTK-Equals}] \item[CCTK\_FirstVarIndex] - [\pageref{FirstVarIndex}] + [\pageref{CCTK-FirstVarIndex}] Given a group name returns the first variable index in the group \item[CCTK\_FirstVarIndexI] - [\pageref{FirstVarIndexI}] + [\pageref{CCTK-FirstVarIndexI}] Given a group index returns the first variable index in the group \item[CCTK\_FortranString] - [\pageref{FortranString}] + [\pageref{CCTK-FortranString}] Changes a C string into a Fortran string \item[CCTK\_FullName] - [\pageref{FullName}] + [\pageref{CCTK-FullName}] Given a variable index, returns the full name of the variable \item[CCTK\_GroupData] - [\pageref{GroupData}] + [\pageref{CCTK-GroupData}] Given a group index, returns information about the variables held in the group \item[CCTK\_GHExtension] - [\pageref{GHExtension}] + [\pageref{CCTK-GHExtension}] Get the pointer to a registered extension to the Cactus GH structure \item[CCTK\_GHExtensionHandle] - [\pageref{GHExtensionHandle}] + [\pageref{CCTK-GHExtensionHandle}] Get the handle associated with a extension to the Cactus GH structure \item[CCTK\_GroupIndex] - [\pageref{GroupIndex}] + [\pageref{CCTK-GroupIndex}] Get the index number for a group name \item[CCTK\_GroupIndexFromVar] - [\pageref{GroupIndexFromVar}] + [\pageref{CCTK-GroupIndexFromVar}] Given a variable name, returns the index of the associated group \item[CCTK\_GroupIndexFromVarI] - [\pageref{GroupIndexFromVarI}] + [\pageref{CCTK-GroupIndexFromVarI}] Given a variable index, returns the index of the associated group \item[CCTK\_GroupName] - [\pageref{GroupName}] + [\pageref{CCTK-GroupName}] Given a group index, returns the group name \item[CCTK\_GroupNameFromVarI] - [\pageref{GroupNameFromVarI}] + [\pageref{CCTK-GroupNameFromVarI}] Given a variable index, return the name of the associated group \item[CCTK\_GroupTypeFromVarI] - [\pageref{GroupTypeFromVarI}] + [\pageref{CCTK-GroupTypeFromVarI}] Provides group type index from the group index \item[CCTK\_ImpFromVarI] - [\pageref{ImpFromVarI}] + [\pageref{CCTK-ImpFromVarI}] Given a variable index, returns the implementation name \item[CCTK\_INFO] - [\pageref{INFO}] + [\pageref{CCTK-INFO}] Prints an information message \item[CCTK\_InterpGV] - [\pageref{InterpGV}] + [\pageref{CCTK-InterpGV}] Performs an interpolation on a list of distributed CCTK grid variables, using a chosen interpolation operator \item[CCTK\_InterpHandle] - [\pageref{InterpHandle}] + [\pageref{CCTK-InterpHandle}] Returns the handle for a given interpolation operator \item[CCTK\_InterpLocal] - [\pageref{InterpLocal}] + [\pageref{CCTK-InterpLocal}] Performs an interpolation on a list of processor-local arrays, using a chosen interpolation operator \item[CCTK\_InterpRegisterOperatorGV] - [\pageref{InterpRegisterOperatorGV}] + [\pageref{CCTK-InterpRegisterOperatorGV}] Registers a routine as an interpolation operator for distributed CCTK grid variables \item[CCTK\_InterpRegisterOperatorLocal] - [\pageref{InterpRegisterOperatorLocal}] + [\pageref{CCTK-InterpRegisterOperatorLocal}] Registers a routine as an interpolation operator for processor-local arrays \item[CCTK\_IsThornActive] - [\pageref{IsThornActive}] + [\pageref{CCTK-IsThornActive}] Reports whether a thorn was activated in a parameter file \item[CCTK\_MaxDim] - [\pageref{MaxDim}] + [\pageref{CCTK-MaxDim}] Get the maximum dimension of any grid variable \item[CCTK\_MyProc] - [\pageref{MyProc}] + [\pageref{CCTK-MyProc}] Get the local processor number \item[CCTK\_NumGroups] - [\pageref{NumGroups}] + [\pageref{CCTK-NumGroups}] Get the number of groups of variables compiled in the code \item[CCTK\_NumTimeLevelsFromVarI] - [\pageref{NumTimeLevelsFromVarI}] + [\pageref{CCTK-NumTimeLevelsFromVarI}] Gives the number of timelevels for a variable \item[CCTK\_NumTimeLevelsFromVar] - [\pageref{NumTimeLevelsFromVar}] + [\pageref{CCTK-NumTimeLevelsFromVar}] Gives the number of timelevels for a variable \item[CCTK\_NumVars] - [\pageref{NumVars}] + [\pageref{CCTK-NumVars}] Get the number of grid variables compiled in the code \item[CCTK\_NumVarsInGroupI] - [\pageref{NumVarsInGroupI}] + [\pageref{CCTK-NumVarsInGroupI}] Provides the number of variables in a group from the group index \item[CCTK\_NumVarsInGroup] - [\pageref{NumVarsInGroup}] + [\pageref{CCTK-NumVarsInGroup}] Provides the number of variables in a group from the group name \item[CCTK\_nProcs] - [\pageref{nProcs}] + [\pageref{CCTK-nProcs}] Get the total number of processors used \item[CCTK\_OutputGH] - [\pageref{OutputGH}] + [\pageref{CCTK-OutputGH}] \item[CCTK\_OutputVar] - [\pageref{OutputVar}] + [\pageref{CCTK-OutputVar}] \item[CCTK\_OutputVarAs] - [\pageref{OutputVarAs}] + [\pageref{CCTK-OutputVarAs}] \item[CCTK\_OutputVarAsByMethod] - [\pageref{OutputVarAsByMethod}] + [\pageref{CCTK-OutputVarAsByMethod}] \item[CCTK\_OutputVarByMethod] - [\pageref{OutputVarByMethod}] + [\pageref{CCTK-OutputVarByMethod}] \item[CCTK\_ParallelInit] - [\pageref{ParallelInit}] + [\pageref{CCTK-ParallelInit}] \item[CCTK\_PARAMWARN] - [\pageref{PARAMWARN}] + [\pageref{CCTK-PARAMWARN}] Prints a warning from parameter checking, and possibly stops the code \item[CCTK\_PrintGroup] - [\pageref{PrintGroup}] + [\pageref{CCTK-PrintGroup}] Prints a group name from its index \item[CCTK\_PrintString] - [\pageref{PrintString}] + [\pageref{CCTK-PrintString}] Prints a Cactus string to screen (from Fortran) \item[CCTK\_PrintVar] - [\pageref{PrintVar}] + [\pageref{CCTK-PrintVar}] Prints a variable name from its index \item[CCTK\_QueryGroupStorage] - [\pageref{QueryGroupStorage}] + [\pageref{CCTK-QueryGroupStorage}] \item[CCTK\_QueryGroupStorageI] - [\pageref{QueryGroupStorageI}] + [\pageref{CCTK-QueryGroupStorageI}] %\item[CCTK\_Reduce] -% [\pageref{Reduce}] +% [\pageref{CCTK-Reduce}] % Perform a reduction operation using a registered operator \item[CCTK\_ReductionHandle] - [\pageref{ReductionHandle}] + [\pageref{CCTK-ReductionHandle}] Get the handle for a registered reduction operator \item[CCTK\_RegisterBanner] - [\pageref{RegisterBanner}] + [\pageref{CCTK-RegisterBanner}] Register a banner for a thorn \item[CCTK\_RegisterGHExtension] - [\pageref{RegisterGHExtension}] + [\pageref{CCTK-RegisterGHExtension}] Register the name of an extension to the Cactus GH. \item[CCTK\_RegisterGHExtensionInitGH] - [\pageref{RegisterGHExtensionInitGH}] + [\pageref{CCTK-RegisterGHExtensionInitGH}] Register a routine for providing initialisation for an extension to the Cactus GH \item[CCTK\_RegisterGHExtensionSetupGH] - [\pageref{RegisterGHExtensionSetupGH}] + [\pageref{CCTK-RegisterGHExtensionSetupGH}] Register a routine for setting up an extension to the Cactus GH \item[CCTK\_RegisterGHExtensionScheduleTraverseGH] - [\pageref{RegisterGHExtensionScheduleTraverseGH}] + [\pageref{CCTK-RegisterGHExtensionScheduleTraverseGH}] Register a GH extension schedule traversal routine \item[CCTK\_RegisterIOMethod] - [\pageref{RegisterIOMethod}] + [\pageref{CCTK-RegisterIOMethod}] Register an IO method name \item[CCTK\_RegisterIOMethodOutputGH] - [\pageref{RegisterIOMethodOutputGH}] + [\pageref{CCTK-RegisterIOMethodOutputGH}] \item[CCTK\_RegisterIOMethodOutputVarAs] - [\pageref{RegisterIOMethodOutputVarAs}] + [\pageref{CCTK-RegisterIOMethodOutputVarAs}] \item[CCTK\_RegisterIOMethodTimeToOutput] - [\pageref{RegisterIOMethodTimeToOutput}] + [\pageref{CCTK-RegisterIOMethodTimeToOutput}] Register a routine for deciding if it is time to output for an IO method \item[CCTK\_RegisterIOMethodTriggerOutput] - [\pageref{RegisterIOMethodTriggerOutput}] + [\pageref{CCTK-RegisterIOMethodTriggerOutput}] Register a routine for dealing with trigger output for an IO method \item[CCTK\_RegisterReductionOperator] - [\pageref{RegisterReductionOperator}] + [\pageref{CCTK-RegisterReductionOperator}] Register a function as providing a reduction operation \item[CCTK\_SetupGH] - [\pageref{SetupGH}] + [\pageref{CCTK-SetupGH}] \item[CCTK\_SyncGroup] - [\pageref{SyncGroup}] + [\pageref{CCTK-SyncGroup}] Synchronize the ghost zones for a group of variables \item[CCTK\_VarDataPtr] - [\pageref{VarDataPtr}] + [\pageref{CCTK-VarDataPtr}] Returns the data pointer for a grid variable \item[CCTK\_VarDataPtrB] - [\pageref{VarDataPtrB}] + [\pageref{CCTK-VarDataPtrB}] Returns the data pointer for a grid variable from the variable index or name \item[CCTK\_VarDataPtrI] - [\pageref{VarDataPtrI}] + [\pageref{CCTK-VarDataPtrI}] Returns the data pointer for a grid variable from the variable index \item[CCTK\_VarIndex] - [\pageref{VarIndex}] + [\pageref{CCTK-VarIndex}] Get the index for a variable \item[CCTK\_VarName] - [\pageref{VarName}] + [\pageref{CCTK-VarName}] Given a variable index, returns the variable name \item[CCTK\_VarTypeI] - [\pageref{VarTypeI}] + [\pageref{CCTK-VarTypeI}] Provides variable type index from the variable index \item[CCTK\_WARN] - [\pageref{WARN}] + [\pageref{CCTK-WARN}] Prints a warning message and possibly stops the code \end{Lentry} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Full Description of Functions} @@ -420,7 +434,7 @@ available from C, not all are currently available from Fortran. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_Abort}{Exit the code abruptly} -\label{Abort} +\label{CCTK-Abort} \subroutine{int}{integer}{istat} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \argument{int}{integer}{value} @@ -445,7 +459,7 @@ available from C, not all are currently available from Fortran. % cctk_Comm.h \begin{CCTKFunc}{CCTK\_ArrayGroupSize}{} -\label{ArrayGroupSize} +\label{CCTK-ArrayGroupSize} \subroutine{int *}{}{size} \argument{cGH *}{}{cctkGH} \argument{const char *}{}{groupname} @@ -466,7 +480,7 @@ available from C, not all are currently available from Fortran. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_ArrayGroupSizeB}{} -\label{ArrayGroupSizeB} +\label{CCTK-ArrayGroupSizeB} \subroutine{int *}{}{size} \argument{cGH *}{}{cctkGH} \argument{int}{}{groupindex} @@ -489,7 +503,7 @@ available from C, not all are currently available from Fortran. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_ArrayGroupSizeI}{} -\label{ArrayGroupSizeI} +\label{CCTK-ArrayGroupSizeI} \subroutine{int *}{}{size} \argument{cGH *}{}{cctkGH} \argument{int}{}{dir} @@ -517,7 +531,7 @@ available from C, not all are currently available from Fortran. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_Barrier}{} -\label{Barrier} +\label{CCTK-Barrier} \subroutine{int}{integer}{istat} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \showcargs @@ -541,7 +555,7 @@ available from C, not all are currently available from Fortran. \begin{CCTKFunc}{CCTK\_Cmplx}{Turns two real numbers into a complex number} -\label{Cmplx} +\label{CCTK-Cmplx} \subroutine{CCTK\_COMPLEX}{}{cmpno} \argument{CCTK\_REAL}{}{realpart} \argument{CCTK\_REAL}{}{imagpart} @@ -564,7 +578,7 @@ available from C, not all are currently available from Fortran. \begin{CCTKFunc}{CCTK\_CmplxAbs}{Absolute value of a complex number} -\label{CmplxAbs} +\label{CCTK-CmplxAbs} \subroutine{CCTK\_COMPLEX}{}{absval} \argument{CCTK\_COMPLEX}{}{inval} \showcargs @@ -585,7 +599,7 @@ available from C, not all are currently available from Fortran. \begin{CCTKFunc}{CCTK\_CmplxAdd}{Sum of two complex numbers} -\label{CmplxAdd} +\label{CCTK-CmplxAdd} \subroutine{CCTK\_COMPLEX}{}{addval} \argument{CCTK\_COMPLEX}{}{inval1} \argument{CCTK\_COMPLEX}{}{inval2} @@ -607,7 +621,7 @@ available from C, not all are currently available from Fortran. \end{CCTKFunc} \begin{CCTKFunc}{CCTK\_CmplxConjg}{Complex conjugate of a complex number} -\label{CmplxConjg} +\label{CCTK-CmplxConjg} \subroutine{CCTK\_COMPLEX}{}{conjgval} \argument{CCTK\_COMPLEX}{}{inval} \showcargs @@ -627,7 +641,7 @@ available from C, not all are currently available from Fortran. \end{CCTKFunc} \begin{CCTKFunc}{CCTK\_CmplxCos}{Cosine of a complex number} -\label{CmplxCos} +\label{CCTK-CmplxCos} \subroutine{CCTK\_COMPLEX}{}{cosval} \argument{CCTK\_COMPLEX}{}{inval} \showcargs @@ -649,7 +663,7 @@ available from C, not all are currently available from Fortran. \begin{CCTKFunc}{CCTK\_CmplxDiv}{Division of two complex numbers} -\label{CmplxDiv} +\label{CCTK-CmplxDiv} \subroutine{CCTK\_COMPLEX}{}{divval} \argument{CCTK\_COMPLEX}{}{inval1} \argument{CCTK\_COMPLEX}{}{inval2} @@ -672,7 +686,7 @@ available from C, not all are currently available from Fortran. \begin{CCTKFunc}{CCTK\_CmplxExp}{Exponent of a complex number} -\label{CmplxExp} +\label{CCTK-CmplxExp} \subroutine{CCTK\_COMPLEX}{}{expval} \argument{CCTK\_COMPLEX}{}{inval} \showcargs @@ -693,7 +707,7 @@ available from C, not all are currently available from Fortran. \end{CCTKFunc} \begin{CCTKFunc}{CCTK\_CmplxImag}{Imaginary part of a complex number} -\label{CmplxImag} +\label{CCTK-CmplxImag} \subroutine{CCTK\_REAL}{}{imval} \argument{CCTK\_COMPLEX}{}{inval} \showcargs @@ -714,7 +728,7 @@ The imaginary part of a complex number $z=a+bi$ is $b$. \end{CCTKFunc} \begin{CCTKFunc}{CCTK\_CmplxLog}{Logarithm of a complex number} -\label{CmplxLog} +\label{CCTK-CmplxLog} \subroutine{CCTK\_COMPLEX}{}{logval} \argument{CCTK\_COMPLEX}{}{inval} \showcargs @@ -735,7 +749,7 @@ The imaginary part of a complex number $z=a+bi$ is $b$. \end{CCTKFunc} \begin{CCTKFunc}{CCTK\_CmplxMul}{Multiplication of two complex numbers} -\label{CmplxMul} +\label{CCTK-CmplxMul} \subroutine{CCTK\_COMPLEX}{}{mulval} \argument{CCTK\_COMPLEX}{}{inval1} \argument{CCTK\_COMPLEX}{}{inval2} @@ -761,7 +775,7 @@ $z=(a_1 a_2 - b_1 b_2) + (a_1 b_2 + a_2 b_1)i$. \begin{CCTKFunc}{CCTK\_CmplxReal}{Real part of a complex number} -\label{CmplxReal} +\label{CCTK-CmplxReal} \subroutine{CCTK\_REAL}{}{reval} \argument{CCTK\_COMPLEX}{}{inval} \showcargs @@ -782,7 +796,7 @@ The real part of a complex number $z=a+bi$ is $a$. \end{CCTKFunc} \begin{CCTKFunc}{CCTK\_CmplxSin}{Sine of a complex number} -\label{CmplxSin} +\label{CCTK-CmplxSin} \subroutine{CCTK\_COMPLEX}{}{sinval} \argument{CCTK\_COMPLEX}{}{inval} \showcargs @@ -804,7 +818,7 @@ The real part of a complex number $z=a+bi$ is $a$. \begin{CCTKFunc}{CCTK\_CmplxSub}{Subtraction of two complex numbers} -\label{CmplxSub} +\label{CCTK-CmplxSub} \subroutine{CCTK\_COMPLEX}{}{subval} \argument{CCTK\_COMPLEX}{}{inval1} \argument{CCTK\_COMPLEX}{}{inval2} @@ -830,7 +844,7 @@ $$ \end{CCTKFunc} \begin{CCTKFunc}{CCTK\_CmplxSqrt}{Square root of a complex number} -\label{CmplxSqrt} +\label{CCTK-CmplxSqrt} \subroutine{CCTK\_COMPLEX}{}{sqrtval} \argument{CCTK\_COMPLEX}{}{inval} \showcargs @@ -853,7 +867,7 @@ $$ \begin{CCTKFunc}{CCTK\_CoordSystemDim}{Give the dimension for a given coordinate system.} -\label{CoordDim} +\label{CCTK-CoordDim} \subroutine{int}{integer}{dim} \argument{const char *}{character*(*)}{systemname} \showargs @@ -877,7 +891,7 @@ $$ \begin{CCTKFunc}{CCTK\_CoordDir}{Give the direction for a given coordinate.} -\label{CoordDir} +\label{CCTK-CoordDir} \subroutine{int}{integer}{dir} \argument{const char *}{character*(*)}{coordname} \argument{const char *}{character*(*)}{systemname} @@ -904,7 +918,7 @@ The coordinate name is independent of the grid function name. \begin{CCTKFunc}{CCTK\_CoordIndex}{Give the grid variable index for a given coordinate.} -\label{CoordIndex} +\label{CCTK-CoordIndex} \subroutine{int}{integer}{index} \argument{int}{integer}{direction} \argument{const char *}{character*(*)}{coordname} @@ -940,7 +954,7 @@ will be used if the coordinate direction is given as less than or equal to zero, % Coord.c \begin{CCTKFunc}{CCTK\_CoordRange}{Return the global upper and lower bounds for a given coordinate} -\label{CoordRange} +\label{CCTK-CoordRange} \subroutine{int}{integer}{ierr} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \argument{CCTK\_REAL}{CCTK\_REAL}{lower} @@ -981,7 +995,7 @@ name will be used. % Coord.c \begin{CCTKFunc}{CCTK\_CoordRegisterData}{Define a coordinate in a given coordinate system.} -\label{CoordRegisterData} +\label{CCTK-CoordRegisterData} \subroutine{int}{integer}{ierr} \argument{int}{integer}{direction} \argument{const char *}{character*(*)}{gvname} @@ -1016,7 +1030,7 @@ using {\tt CCTK\_CoordRegisterSystem}. % Coord.c \begin{CCTKFunc}{CCTK\_CoordRegisterRange}{Assign the global maximum and minimum values of a coordinate on a given grid hierachy} -\label{CoordRegisterRange} +\label{CCTK-CoordRegisterRange} \subroutine{int}{integer}{ierr} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \argument{CCTK\_REAL}{CCTK\_REAL}{min} @@ -1061,7 +1075,7 @@ can be accessed by {\t CCTK\_CoordRange}. % Coord.c \begin{CCTKFunc}{CCTK\_CoordRegisterSystem}{Assigns a coordinate system with a chosen name and dimension} -\label{CoordRegisterSystem} +\label{CCTK-CoordRegisterSystem} \subroutine{int}{integer}{ierr} \argument{int}{integer}{dimension} \argument{const char *}{character*(*)}{systemname} @@ -1089,7 +1103,7 @@ a chosen name and dimension} % Coord.c \begin{CCTKFunc}{CCTK\_CoordSystemHandle}{Returns the handle associated with a registered coordinate system} -\label{CoordSystemHandle} +\label{CCTK-CoordSystemHandle} \subroutine{int}{integer}{handle} \argument{const char *}{character*(*)}{systemname} \showargs @@ -1116,7 +1130,7 @@ A negative return code indicates an invalid coordinate system name. % Coord.c \begin{CCTKFunc}{CCTK\_CoordSystemName}{Returns the name of a registered coordinate system} -\label{CoordSystemName} +\label{CCTK-CoordSystemName} \subroutine{const char *}{integer}{systemname} \argument{int}{integer}{handle} \showcargs @@ -1144,7 +1158,7 @@ A NULL pointer is returned if an invalid handle was given. % Coord.c \begin{CCTKFunc}{CCTK\_CreateDirectory}{Create a directory with required permissions} -\label{CreateDirectory} +\label{CCTK-CreateDirectory} \subroutine{int}{integer}{ierr} \argument{const char *}{character*(*)}{pathname} \argument{int}{integer}{mode} @@ -1183,7 +1197,7 @@ To create a directory readable by everyone, but writeable only by the user runnn % CommOverloadables.c \begin{CCTKFunc}{CCTK\_DisableGroupComm}{Turn communications off for a group of grid variables} -\label{DisableGroupComm} +\label{CCTK-DisableGroupComm} \subroutine{int}{integer}{istat} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \argument{const char *}{character*(*)}{group} @@ -1208,7 +1222,7 @@ communications are all off. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_DisableGroupStorage}{Free the storage associated with a group of grid variables} -\label{DisableGroupStorage} +\label{CCTK-DisableGroupStorage} \subroutine{int}{integer}{istat} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \argument{const char *}{character*(*)}{group} @@ -1230,7 +1244,7 @@ communications are all off. % Groups.c \begin{CCTKFunc}{CCTK\_DecomposeName}{Given the full name of a variable/group, separates the name returning both the implementation and the variable/group} -\label{DecomposeName} +\label{CCTK-DecomposeName} \subroutine{int}{integer}{istat} \argument{char *}{}{fullname} \argument{char **}{}{imp} @@ -1265,7 +1279,7 @@ No Fortran routine exists at the moment. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_EnableGroupComm}{Turn communications on for a group of grid variables} -\label{EnableGroupComm} +\label{CCTK-EnableGroupComm} \subroutine{int}{integer}{istat} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \argument{const char *}{character*(*)}{group} @@ -1291,7 +1305,7 @@ file. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_EnableGroupStorage}{Assign the storage for a group of grid variables} -\label{EnableGroupStorage} +\label{CCTK-EnableGroupStorage} \subroutine{int}{integer}{istat} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \argument{const char *}{character*(*)}{group} @@ -1314,7 +1328,7 @@ the Cactus scheduler via a thorn's {\tt schedule.ccl} file. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_Equals}{Check for string equality} -\label{Equals} +\label{CCTK-Equals} \function{int}{integer}{istat} \argument{const char *}{character*(*)}{string1} \argument{const char *}{character*(*)}{string2} @@ -1339,7 +1353,7 @@ and zero if they differ. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_Exit}{Exit the code cleanly} -\label{Exit} +\label{CCTK-Exit} \subroutine{int}{integer}{istat} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \argument{int}{integer}{value} @@ -1368,7 +1382,7 @@ and zero if they differ. % Groups.c \begin{CCTKFunc}{CCTK\_FirstVarIndex}{Given a group name returns the first variable index in the group} -\label{FirstVarIndex} +\label{CCTK-FirstVarIndex} \subroutine{int}{integer}{firstvar} \argument{const char *}{character*(*)}{group} \showargs @@ -1393,7 +1407,7 @@ and zero if they differ. \begin{CCTKFunc}{CCTK\_FirstVarIndexI}{Given a group index returns the first variable index in the group} -\label{FirstVarIndexI} +\label{CCTK-FirstVarIndexI} \subroutine{int}{integer}{firstvar} \argument{int}{integer}{group} \showargs @@ -1419,7 +1433,7 @@ and zero if they differ. \begin{CCTKFunc}{CCTK\_FortranString}{Changes a C string into a Fortran string} -\label{FortranString} +\label{CCTK-FortranString} \subroutine{int}{integer}{nchar} \argument{const char *}{character*(*)}{strout} \argument{const char *}{CCTK\_STRING}{strin} @@ -1449,7 +1463,7 @@ strings. This routine allows a Fortran string to be created from such a C string % Groups.c \begin{CCTKFunc}{CCTK\_FullName}{Given a variable index, returns the full name of the variable} -\label{FullName} +\label{CCTK-FullName} \subroutine{char *}{integer}{fullname} \argument{int}{integer}{index} \showcargs @@ -1481,7 +1495,7 @@ the form {\t <implementation>::<variable>} % cctk_GHExtensions.h \begin{CCTKFunc}{CCTK\_GHExtension}{Get the pointer to a registered extension to the Cactus GH structure} -\label{GHExtension} +\label{CCTK-GHExtension} \subroutine{int}{integer}{extension} \argument{GH *}{CCTK\_POINTER}{cctkGH} \showcargs @@ -1507,7 +1521,7 @@ A NULL pointer is returned if an invalid extension name was given. % cctk_GHExtensions.h \begin{CCTKFunc}{CCTK\_GHExtensionHandle}{Get the handle associated with a extension to the Cactus GH structure} -\label{GHExtensionHandle} +\label{CCTK-GHExtensionHandle} \subroutine{int}{integer}{handle} \argument{const char *}{character*(*)}{name} \showargs @@ -1533,7 +1547,7 @@ A NULL pointer is returned if an invalid extension name was given. % Groups.c \begin{CCTKFunc}{CCTK\_GroupTypeFromVarI}{Provides group type index from the group index} -\label{GroupTypeFromVarI} +\label{CCTK-GroupTypeFromVarI} \subroutine{int}{integer}{type} \argument{int}{integer}{index} \showargs @@ -1564,7 +1578,7 @@ with the Cactus provided macros for {\t GROUP\_SCALAR}, {\t GROUP\_GF}, {\t GROU % Groups.c \begin{CCTKFunc}{CCTK\_GroupName}{Given a group index, returns the group name} -\label{GroupName} +\label{CCTK-GroupName} \subroutine{char *}{integer}{name} \argument{int}{integer}{index} \showcargs @@ -1592,7 +1606,7 @@ No Fortran routine exists at the moment. % Groups.c \begin{CCTKFunc}{CCTK\_GroupData}{Given a group index, returns information about the variables held in the group.} -\label{GroupData} +\label{CCTK-GroupData} \function{int}{}{ierr} \argument{int}{}{group} \argument{cGroup *}{}{pgroup} @@ -1617,7 +1631,7 @@ No Fortran routine exists at the moment. \begin{examples} \begin{tabular}{@{}p{3cm}cp{11cm}} \hfill {\bf C} && {\t cGroup pgroup;}\\ - && {\t index = CCTK\_GroupIndex("evolve::scalars")}\\ + && {\t index = CCTK\_GroupIndex("evolve::scalars")}\\ &&{\t ierr = CCTK\_GroupData(index,\&pgroup);}\\ && {\t vtype = pgroup.vartype;} \\ @@ -1631,7 +1645,7 @@ No Fortran routine exists at the moment. % Groups.c \begin{CCTKFunc}{CCTK\_GroupNameFromVarI}{Given a variable index, return the name of the associated group} -\label{GroupNameFromVarI} +\label{CCTK-GroupNameFromVarI} \subroutine{char *}{character*(*)}{group} \argument{int}{integer}{varindex} \showcargs @@ -1656,7 +1670,7 @@ No Fortran routine exists at the moment. % Groups.c \begin{CCTKFunc}{CCTK\_GroupIndexFromVarI}{Given a variable index, returns the index of the associated group} -\label{GroupIndexFromVarI} +\label{CCTK-GroupIndexFromVarI} \subroutine{int}{integer}{groupindex} \argument{int}{integer}{varindex} \showargs @@ -1684,7 +1698,7 @@ No Fortran routine exists at the moment. % Groups.c \begin{CCTKFunc}{CCTK\_GroupIndexFromVar}{Given a variable name, returns the index of the associated group} -\label{GroupIndexFromVar} +\label{CCTK-GroupIndexFromVar} \subroutine{int}{integer}{groupindex} \argument{const char *}{character*(*)}{name} \showargs @@ -1712,7 +1726,7 @@ The variable name should be in the form {\t <implementation>::<variable>} % Groups.c \begin{CCTKFunc}{CCTK\_GroupIndex}{Get the index number for a group name} -\label{GroupIndex} +\label{CCTK-GroupIndex} \subroutine{int}{integer}{index} \argument{const char *}{character*(*)}{groupname} \showargs @@ -1749,7 +1763,7 @@ The group name should be the given in its fully qualified form, that is {\t <imp % Groups.c \begin{CCTKFunc}{CCTK\_ImpFromVarI}{Given a variable index, returns the implementation name} -\label{ImpFromVarI} +\label{CCTK-ImpFromVarI} \subroutine{char *}{integer}{implementation} \argument{int}{integer}{index} \showcargs @@ -1777,7 +1791,7 @@ No Fortran routine exists at the moment % WarnLevel.c \begin{CCTKFunc}{CCTK\_INFO}{Prints an information message} -\label{INFO} +\label{CCTK-INFO} \subroutine{}{}{} \argument{const char *}{character*(*)}{message} \showargs @@ -1803,7 +1817,7 @@ No Fortran routine exists at the moment % Interp.c \begin{CCTKFunc}{CCTK\_InterpGV}{Perform an interpolation on a list of distributed CCTK grid variables, using a chosen interpolation operator} -\label{InterpGV} +\label{CCTK-InterpGV} \subroutine{int}{integer}{ierr} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \argument{int}{integer}{operator\_handle} @@ -1898,7 +1912,7 @@ A negative return code indicates an error condition: % Interp.c \begin{CCTKFunc}{CCTK\_InterpHandle}{Return the handle for a given interpolation operator} -\label{InterpHandle} +\label{CCTK-InterpHandle} \subroutine{int}{integer}{handle} \argument{const char *}{character*(*)}{operator} \showargs @@ -1927,7 +1941,7 @@ A negative value is returned for invalid/unregistered interpolation operator nam % Interp.c \begin{CCTKFunc}{CCTK\_InterpLocal}{Perform an interpolation on a list of processor-local arrays, using a chosen interpolation operator} -\label{InterpLocal} +\label{CCTK-InterpLocal} \subroutine{int}{integer}{ierr} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \argument{int}{integer}{operator\_handle} @@ -2028,7 +2042,7 @@ A negative return code indicates an error condition: % Interp.c \begin{CCTKFunc}{CCTK\_InterpRegisterOperatorGV}{Register a routine as an interpolation operator for distributed CCTK grid variables} -\label{InterpRegisterOperatorGV} +\label{CCTK-InterpRegisterOperatorGV} \subroutine{int}{}{ierr} \argument{cInterpOperatorGV}{}{operator} \argument{const char *}{}{name} @@ -2074,7 +2088,7 @@ A negative return code indicates an error condition: % Interp.c \begin{CCTKFunc}{CCTK\_InterpRegisterOperatorLocal}{Register a routine as an interpolation operator for processor-local arrays} -\label{InterpRegisterOperatorLocal} +\label{CCTK-InterpRegisterOperatorLocal} \subroutine{int}{}{ierr} \argument{cInterpOperatorLocal}{}{operator} \argument{const char *}{}{name} @@ -2140,7 +2154,7 @@ A negative return code indicates an error condition: % CommOverloadables.c \begin{CCTKFunc}{CCTK\_MyProc}{Returns the number of the local processor for a parallel run} -\label{MyProc} +\label{CCTK-MyProc} \function{int}{integer}{myproc} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \showargs @@ -2164,7 +2178,7 @@ runs, this call will return $0\leq myproc < {\t CCTK\_nProcs(cctkGH)}$. % Groups.c \begin{CCTKFunc}{CCTK\_MaxDim}{Get the maximum dimension of any grid variable } -\label{MaxDim} +\label{CCTK-MaxDim} \subroutine{int}{integer}{dim} \showargs \begin{params} @@ -2195,7 +2209,7 @@ and not the active thorn list. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_nProcs}{Returns the number of processors being used for a parallel run} -\label{nProcs} +\label{CCTK-nProcs} \function{int}{integer}{nprocs} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \showargs @@ -2217,7 +2231,7 @@ For a single processor run this call will return one. % Groups.c \begin{CCTKFunc}{CCTK\_NumTimeLevelsFromVarI}{Gives the number of timelevels for a variable} -\label{NumTimeLevelsFromVarI} +\label{CCTK-NumTimeLevelsFromVarI} \subroutine{int}{integer}{numlevels} \argument{int}{integer}{index} \showargs @@ -2245,7 +2259,7 @@ For a single processor run this call will return one. % Groups.c \begin{CCTKFunc}{CCTK\_NumTimeLevelsFromVar}{Gives the number of timelevels for a variable} -\label{NumTimeLevelsFromVar} +\label{CCTK-NumTimeLevelsFromVar} \subroutine{int}{integer}{numlevels} \argument{const char *}{character*(*)}{name} \showargs @@ -2273,7 +2287,7 @@ The variable name should be in the form {\t <implementation>::<variable>} % Groups.c \begin{CCTKFunc}{CCTK\_NumVarsInGroupI}{Provides the number of variables in a group from the group index} -\label{NumVarsInGroupI} +\label{CCTK-NumVarsInGroupI} \subroutine{int}{integer}{num} \argument{int}{integer}{index} \showargs @@ -2302,7 +2316,7 @@ The variable name should be in the form {\t <implementation>::<variable>} % Groups.c \begin{CCTKFunc}{CCTK\_NumVarsInGroup}{Provides the number of variables in a group from the group name} -\label{} +\label{CCTK-NumVarsInGroup} \subroutine{int}{integer}{num} \argument{const char *}{character*(*)}{name} \showargs @@ -2329,7 +2343,7 @@ The group name should be given in the form {\t <implementation>::<group>} % Groups.c \begin{CCTKFunc}{CCTK\_NumGroups}{Get the number of groups of variables compiled in the code} -\label{NumGroups} +\label{CCTK-NumGroups} \subroutine{int}{integer}{number} \showargs \begin{params} @@ -2352,7 +2366,7 @@ The group name should be given in the form {\t <implementation>::<group>} % Groups.c \begin{CCTKFunc}{CCTK\_NumVars}{Get the number of grid variables compiled in the code} -\label{NumVars} +\label{CCTK-NumVars} \subroutine{int}{integer}{number} \showargs \begin{params} @@ -2382,7 +2396,7 @@ The group name should be given in the form {\t <implementation>::<group>} % IOOverloadables.h \begin{CCTKFunc}{CCTK\_OutputVarAs}{} -\label{OutputVarAs} +\label{CCTK-OutputVarAs} \subroutine{int}{}{istat} \argument{cGH *}{}{cctkGH} \argument{const char *}{character*(*)}{variable} @@ -2412,7 +2426,7 @@ of constructing a filename. % IOOverloadables.h \begin{CCTKFunc}{CCTK\_OutputVarAsByMethod}{} -\label{OutputVarAsByMethod} +\label{CCTK-OutputVarAsByMethod} \subroutine{int}{}{istat} \argument{cGH *}{}{cctkGH} \argument{const char *}{character*(*)}{variable} @@ -2443,7 +2457,7 @@ file is created. % IOOverloadables.h \begin{CCTKFunc}{CCTK\_OutputVarByMethod}{} -\label{OutputVarAsMethod} +\label{CCTK-OutputVarAsMethod} \subroutine{int}{}{istat} \argument{cGH *}{}{cctkGH} \argument{const char *}{character*(*)}{variable} @@ -2471,7 +2485,7 @@ file is created. % IOOverloadables.h \begin{CCTKFunc}{CCTK\_OutputVar}{} -\label{OutputVar} +\label{CCTK-OutputVar} \subroutine{int}{}{istat} \argument{cGH *}{}{cctkGH} \argument{const char *}{character*(*)}{variable} @@ -2498,7 +2512,7 @@ file is created. % IOOverloadables.h \begin{CCTKFunc}{CCTK\_OutputGH}{} -\label{OutputGH} +\label{CCTK-OutputGH} \subroutine{int}{integer}{istat} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \showargs @@ -2526,7 +2540,7 @@ file is created. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_ParallelInit}{} -\label{ParallelInit} +\label{CCTK-ParallelInit} \subroutine{int}{integer}{istat} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \showcargs @@ -2547,7 +2561,7 @@ file is created. % Groups.c \begin{CCTKFunc}{CCTK\_PrintGroup}{Prints a group name from its index} -\label{PrintGroup} +\label{CCTK-PrintGroup} \subroutine{}{}{} \argument{int}{integer}{index} \showargs @@ -2571,7 +2585,7 @@ This routine is for debugging purposes for Fortran programmers. % Groups.c \begin{CCTKFunc}{CCTK\_PrintString}{Prints a Cactus string} -\label{PrintString} +\label{CCTK-PrintString} \subroutine{}{}{} \argument{char *}{CCTK\_STRING}{string} \showargs @@ -2599,7 +2613,7 @@ from Fortran. % Groups.c \begin{CCTKFunc}{CCTK\_PrintVar}{Prints a variable name from its index} -\label{PrintVar} +\label{CCTK-PrintVar} \subroutine{}{}{} \argument{int}{integer}{index} \showargs @@ -2625,7 +2639,7 @@ This routine is for debugging purposes for Fortran programmers. % WarnLevel.c \begin{CCTKFunc}{CCTK\_PARAMWARN}{Prints a warning from parameter checking, and possibly stops the code} -\label{PARAMWARN} +\label{CCTK-PARAMWARN} \subroutine{}{}{} \argument{const char *}{character*(*)}{message} \showargs @@ -2659,7 +2673,7 @@ checked. % cctk_Comm.h \begin{CCTKFunc}{CCTK\_QueryGroupStorage}{} -\label{QueryGroupStorage} +\label{CCTK-QueryGroupStorage} \subroutine{int}{}{storage} \argument{cGH *}{}{cctkGH} \argument{const char *}{}{groupname} @@ -2680,7 +2694,7 @@ checked. % cctk_Comm.h \begin{CCTKFunc}{CCTK\_QueryGroupStorageI}{} -\label{QueryGroupStorageI} +\label{CCTK-QueryGroupStorageI} \subroutine{int}{}{storage} \argument{cGH *}{}{cctkGH} \argument{int}{}{groupindex} @@ -2701,7 +2715,7 @@ checked. % CommOverloadables.h \begin{CCTKFunc}{CCTK\_QueryGroupStorageB}{} -\label{QueryGroupStorageB} +\label{CCTK-QueryGroupStorageB} \subroutine{int}{}{storage} \argument{cGH *}{}{cctkGH} \argument{int}{}{groupindex} @@ -2727,7 +2741,7 @@ checked. %%%%% \begin{CCTKFunc}{CCTK\_ReductionHandle}{Handle for given reduction method} -\label{ReductionHandle} +\label{CCTK-ReductionHandle} \function{int}{integer}{handle} \argument{const char *}{character*(*)}{reduction} \showargs @@ -2756,7 +2770,7 @@ operator is case dependent. \begin{CCTKFunc}{CCTK\_RegisterIOMethod}{} -\label{RegisterIOMethod} +\label{CCTK-RegisterIOMethod} \function{int}{integer}{handle} \argument{const char *}{}{name} \showargs @@ -2778,7 +2792,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}. % cctk_IOMethods.h \begin{CCTKFunc}{CCTK\_RegisterIOMethodOutputGH}{Register a routine for an IO method which will be called from {\tt CCTK\_OutputGH}.} -\label{RegisterIOMethodOutputGH} +\label{CCTK-RegisterIOMethodOutputGH} \function{int}{integer}{istat} \argument{int}{}{handle} \argument{int}{}{(* func)(cGH *)} @@ -2799,7 +2813,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}. % cctk_IOMethods.h \begin{CCTKFunc}{CCTK\_RegisterIOMethodTimeToOutput}{Register a routine for an IO method which will decide if it is time for the method to output.} -\label{RegisterIOMethodTimeToOutput} +\label{CCTK-RegisterIOMethodTimeToOutput} \function{int}{integer}{istat} \argument{int}{}{handle} \argument{int}{}{(* func)(cGH *,int)} @@ -2819,7 +2833,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}. % cctk_IOMethods.h \begin{CCTKFunc}{CCTK\_RegisterIOMethodTriggerOutput}{Register a routine for an IO method which will handle trigger output} -\label{RegisterIOMethodTriggerOutput} +\label{CCTK-RegisterIOMethodTriggerOutput} \function{int}{integer}{istat} \argument{int}{}{handle} \argument{int}{}{(* func)(cGH *,int)} @@ -2839,7 +2853,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}. % cctk_IOMethods.h \begin{CCTKFunc}{CCTK\_RegisterIOMethodOutputVarAs}{Register a routine for an IO method which will provide aliased variable output} -\label{RegisterIOMethodOutputVarAs} +\label{CCTK-RegisterIOMethodOutputVarAs} \function{int}{integer}{istat} \argument{int}{}{handle} \argument{int}{}{(* func)(cGH *,const char*, const char *)} @@ -2860,7 +2874,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}. % cctk_GHExtensions.h \begin{CCTKFunc}{CCTK\_RegisterGHExtension}{Register an extension to the CactusGH} -\label{RegisterGHExtension} +\label{CCTK-RegisterGHExtension} \function{int}{}{istat} \argument{const char *}{}{name} \showcargs @@ -2878,7 +2892,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}. % cctk_GHExtensions.h \begin{CCTKFunc}{CCTK\_RegisterGHExtensionSetupGH}{Register a function which will set up a given extension to the Cactus GH} -\label{RegisterGHExtensionSetupGH} +\label{CCTK-RegisterGHExtensionSetupGH} \function{int}{}{istat} \argument{int}{}{handle} \argument{void *}{}{(*func)(tFleshConfig *, int, cGH *)} @@ -2897,7 +2911,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}. % cctk_GHExtensions.h \begin{CCTKFunc}{CCTK\_RegisterGHExtensionInitGH}{Register a function which will initialise a given extension to the Cactus GH} -\label{RegisterGHExtensionInitGH} +\label{CCTK-RegisterGHExtensionInitGH} \function{int}{}{istat} \argument{int}{}{handle} \argument{void *}{}{(*func)(cGH *)} @@ -2916,7 +2930,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}. % cctk_GHExtensions.h \begin{CCTKFunc}{CCTK\_RegisterGHExtensionScheuldeTraverseGH}{Register a GH extension schedule traversal routine} -\label{RegisterGHExtensionrfrTraverseGH} +\label{CCTK-RegisterGHExtensionrfrTraverseGH} \function{int}{}{istat} \argument{int}{}{handle} \argument{int}{}{(*func)(cGH *,const char *)} @@ -2937,7 +2951,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}. % Coord.c \begin{CCTKFunc}{CCTK\_RegisterBanner}{Register a banner for a thorn} -\label{RegisterBanner} +\label{CCTK-RegisterBanner} \subroutine{void}{}{} \argument{const char *}{character*(*)}{message} \showargs @@ -2968,7 +2982,7 @@ displayed in the order in which they are registered. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_SetupGH}{Setup a new GH} -\label{SetupGH} +\label{CCTK-SetupGH} \subroutine{cGH *}{}{cctkGH} \argument{tFleshConfig}{}{config} \argument{int}{}{convlevel} @@ -2990,7 +3004,7 @@ displayed in the order in which they are registered. % CommOverloadables.c \begin{CCTKFunc}{CCTK\_SyncGroup}{Synchronise the ghostzones for a group of grid variables} -\label{SyncGroup} +\label{CCTK-SyncGroup} \subroutine{int}{integer}{istat} \argument{cGH *}{CCTK\_POINTER}{cctkGH} \argument{const char *}{character*(*)}{group} @@ -3035,7 +3049,7 @@ the preferred method from synchronising variables. % Groups.c \begin{CCTKFunc}{CCTK\_VarIndex}{Get the index for a variable} -\label{VarIndex} +\label{CCTK-VarIndex} \subroutine{int}{integer}{index} \argument{const char *}{character*(*)}{varname} \showargs @@ -3062,7 +3076,7 @@ The variable name should be the given in its fully qualified form, that is {\t < % Groups.c \begin{CCTKFunc}{CCTK\_VarName}{Given a variable index, returns the variable name} -\label{VarName} +\label{CCTK-VarName} \subroutine{char *}{integer}{name} \argument{int}{integer}{index} \showcargs @@ -3089,7 +3103,7 @@ No Fortran routine exists at the moment. % Groups.c \begin{CCTKFunc}{CCTK\_VarTypeI}{Provides variable type index from the variable index} -\label{VarTypeI} +\label{CCTK-VarTypeI} \subroutine{int}{integer}{type} \argument{int}{integer}{index} \showargs @@ -3117,7 +3131,7 @@ with the Cactus provided macros for {\t CCTK\_VARIABLE\_INT}, {\t CCTK\_VARIABLE \begin{CCTKFunc}{CCTK\_VarDataPtr}{Returns the data pointer for a grid variable} -\label{VarDataPtr} +\label{CCTK-VarDataPtr} \subroutine{void *}{}{ptr} \argument{cGH *}{}{cctkGH} \argument{int}{}{timelevel} @@ -3142,7 +3156,7 @@ The variable name should be in the form {\t <implementation>::<variable>}. \end{CCTKFunc} \begin{CCTKFunc}{CCTK\_VarDataPtrI}{Returns the data pointer for a grid variable from the variable index} -\label{VarDataPtrI} +\label{CCTK-VarDataPtrI} \subroutine{void *}{}{ptr} \argument{cGH *}{}{cctkGH} \argument{int}{}{timelevel} @@ -3167,7 +3181,7 @@ The variable name should be in the form {\t <implementation>::<variable>}. \begin{CCTKFunc}{CCTK\_VarDataPtrB}{Returns the data pointer for a grid variable from the variable index or the variable name} -\label{VarDataPtrB} +\label{CCTK-VarDataPtrB} \subroutine{void *}{}{ptr} \argument{cGH *}{}{cctkGH} \argument{int}{}{timelevel} @@ -3204,7 +3218,7 @@ If the name if {\t NULL} the index will be used, if the index is negative the na % WarnLevel.c \begin{CCTKFunc}{CCTK\_WARN}{Prints a warning message and possibly stops the code} -\label{WARN} +\label{CCTK-WARN} \subroutine{}{}{} \argument{int}{integer}{level} \argument{const char *}{character*(*)}{warning} @@ -3268,6 +3282,2049 @@ to the standard function {\tt CCTK\_WARN}, for example \end{errorcodes} \end{CCTKFunc} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\chapter{Utility Functions} + +In this section all \hbox{{\tt Util\_}*} Cactus utility functions are +described. These are low-level functions mainly for more complicated +programming, which are used by the rest of Cactus, but don't depend +heavily on it. Some of them are callable from Fortran or C, but +many are C-only. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Functions Alphabetically} + +\begin{Lentry} + +%%\item[Util\_asprintf] +%% [\pageref{Util-asprintf}] + +%%\item[Util\_BinTreeFindNode] +%% [\pageref{Util-BinTreeFindNode}] + +%%\item[Util\_BinTreePrintNodes] +%% [\pageref{Util-BinTreePrintNodes}] + +%%\item[Util\_BinTreeStoreData] +%% [\pageref{Util-BinTreeStoreData}] + +%%\item[Util\_BinTreeTraverseInorder] +%% [\pageref{Util-BinTreeTraverseInorder}] + +%%\item[Util\_BinTreeTraversePostorder] +%% [\pageref{Util-BinTreeTraversePostorder}] + +%%\item[Util\_BinTreeTraversePreorder] +%% [\pageref{Util-BinTreeTraversePreorder}] + +%%\item[Util\_CacheMalloc] +%% [\pageref{Util-CacheMalloc}] + +%%\item[Util\_CurrentDate] +%% [\pageref{Util-CurrentDate}] + +%%\item[Util\_CurrentTime] +%% [\pageref{Util-CurrentTime}] + +%%\item[Util\_DeleteHandle] +%% [\pageref{Util-DeleteHandle}] + +%%\item[Util\_DoubleInRange] +%% [\pageref{Util-DoubleInRange}] + +%%\item[Util\_DoubleInRangeList] +%% [\pageref{Util-DoubleInRangeList}] + +%%\item[Util\_GetHandle] +%% [\pageref{Util-GetHandle}] + +%%\item[Util\_GetHandleName] +%% [\pageref{Util-GetHandleName}] + +%%\item[Util\_GetHandledData] +%% [\pageref{Util-GetHandledData}] + +%%\item[Util\_GetHostName] +%% [\pageref{Util-GetHostName}] + +%%\item[Util\_HashAdd] +%% [\pageref{Util-HashAdd}] + +%%\item[Util\_HashCreate] +%% [\pageref{Util-HashCreate}] + +%%\item[Util\_HashData] +%% [\pageref{Util-HashData}] + +%%\item[Util\_HashDelete] +%% [\pageref{Util-HashDelete}] + +%%\item[Util\_HashDestroy] +%% [\pageref{Util-HashDestroy}] + +%%\item[Util\_HashHash] +%% [\pageref{Util-HashHash}] + +%%\item[Util\_HashStore] +%% [\pageref{Util-HashStore}] + +%%\item[Util\_InList] +%% [\pageref{Util-InList}] + +%%\item[Util\_IntInRange] +%% [\pageref{Util-IntInRange}] + +%%\item[Util\_IntInRangeList] +%% [\pageref{Util-IntInRangeList}] + +%%\item[Util\_NewHandle] +%% [\pageref{Util-NewHandle}] + +%%\item[Util\_NullTerminateString] +%% [\pageref{Util-NullTerminateString}] + +%%\item[Util\_SplitFilename] +%% [\pageref{Util-SplitFilename}] + +%%\item[Util\_SplitString] +%% [\pageref{Util-SplitString}] + +%%\item[Util\_StrCmpi] +%% [\pageref{Util-StrCmpi}] + +%%\item[Util\_Strdup] +%% [\pageref{Util-Strdup}] + +%%\item[Util\_StringListAdd] +%% [\pageref{Util-StringListAdd}] + +%%\item[Util\_StringListCreate] +%% [\pageref{Util-StringListCreate}] + +%%\item[Util\_StringListDestroy] +%% [\pageref{Util-StringListDestroy}] + +%%\item[Util\_StringListNext] +%% [\pageref{Util-StringListNext}] + +\item[Util\_TableCreate] + [\pageref{Util-TableCreate}] +Creates a new (empty) table + +\item[Util\_TableCreateFromString] + [\pageref{Util-TableCreateFromString}] +Creates a new table based on a string argument, which is interpreted +with ``parameter-file'' semantics (the table has the case-insensitive +and auto-destroy flags set) + +\item[Util\_TableDeleteKey] + [\pageref{Util-TableDeleteKey}] +Deletes a specified key/value entry from a table + +\item[Util\_TableDestroy] + [\pageref{Util-TableDestroy}] +Destroys a table + +\item[Util\_TableGet*] + [\pageref{Util-TableGet*}] +Get the single (1-element array) value, or more generally the first +array element of the value, associated with a specified key in a +key/value table. + +\item[Util\_TableGet*Array] + [\pageref{Util-TableGet*Array}] +This is a family of functions, one for each Cactus data type, to get +a copy of the value associated with a specified key, and store it +(more accurately, as much of it as will fit) in a specified array + +\item[Util\_TableGetString] + [\pageref{Util-TableGetString}] +Gets a copy of the character-string value associated with a specified +key in a table, and stores it (more accurately, as much of it as will fit) +in a specified character string + +\item[Util\_TableItAdvance] + [\pageref{Util-TableItAdvance}] +Advance a table iterator to the next entry in the table + +\item[Util\_TableItCreate] + [\pageref{Util-TableItCreate}] +Create a new table iterator + +\item[Util\_TableItDestroy] + [\pageref{Util-TableItDestroy}] +Destroy a table iterator + +\item[Util\_TableItQueryIsNonNull] + [\pageref{Util-TableItQueryIsNonNull}] +Query whether a table iterator is {\em not\/} in the ``null-pointer'' state + +\item[Util\_TableItQueryIsNull] + [\pageref{Util-TableItQueryIsNull}] +Query whether a table iterator is in the ``null-pointer'' state + +\item[Util\_TableItQueryKeyValueInfo] + [\pageref{Util-TableItQueryKeyValueInfo}] +Query the key and the type and number of elements of the value +corresponding to that key, of the table entry to which an iterator points + +\item[Util\_TableItQueryTableHandle] + [\pageref{Util-TableItQueryTableHandle}] +Query what table a table iterator iterates over + +\item[Util\_TableItResetToStart] + [\pageref{Util-TableItResetToStart}] +Reset a table iterator to point to the starting table entry + +\item[Util\_TableItSetToKey] + [\pageref{Util-TableItSetToKey}] +Set a key/value iterator to point to a specified entry in the table. + +\item[Util\_TableItSetToNull] + [\pageref{Util-TableItSetToNull}] +Set a key/value iterator to the "null-pointer" state. + +\item[Util\_TableQueryFlags] + [\pageref{Util-TableQueryFlags}] +Queries a table's flags word + +\item[Util\_TableQueryValueInfo] + [\pageref{Util-TableQueryValueInfo}] +Queries whether or not a specified key is in the table, and optionally +the type and/or number of elements of the value corresponding to this key + +\item[Util\_TableQueryMaxKeyLength] + [\pageref{Util-TableQueryMaxKeyLength}] +Queries the maximum key length in a table + +\item[Util\_TableQueryNKeys] + [\pageref{Util-TableQueryNKeys}] +Queries the number of key/value entries in a table + +\item[Util\_TableSet*] + [\pageref{Util-TableSet*}] +This is a family of functions, one for each Cactus data type, +to set the value associated with a specified key to be a specified +single (1-element array) value + +\item[Util\_TableSet*Array] + [\pageref{Util-TableSet*Array}] +This is a family of functions, one for each Cactus data type, +to set the value associated with a specified key to be a copy +of a specified array + +\item[Util\_TableSetString] + [\pageref{Util-TableSetString}] +Sets the value associated with a specified key in a table, to be +a copy of a specified C-style null-terminated character string + +\end{Lentry} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Full Description of Functions} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableCreate} +\label{Util-TableCreate} +Creates a new (empty) table + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int handle = Util_TableCreate(int flags); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{handle ($\ge 0$)} +A handle to the newly-created table +\end{Result} + +\begin{Parameter}{flags ($\ge 0$)} +A flags word for the table. This should be the inclusive-or of zero +or more of the \verb|UTIL_TABLE_FLAGS_|* bit masks (defined in +\verb|"util_Table.h"|). For Fortran users, note that inclusive-or +is the same as sum here, since the bit masks are all disjoint. +\end{Parameter} + +\begin{Discussion} +We require the flags word to be non-negative so that other +functions can distinguish flags from (negative) error codes. +\NewPar +Any User-defined flag words should use only bit positions at or above +\verb|UTIL_TABLE_FLAGS_USER_DEFINED_BASE|, i.e. all bit positions +below this are reserved for present of future Cactus use. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableCreateFromString()} +simplified interface to create a table and populate it +with entries based on a parameter-file--like character string +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableDestroy()} +destroy a table +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_NO\_MEMORY} +unable to allocate memory +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_FLAGS} +flags word is negative +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" + +/* create a table, simplest case */ +int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT); + +/* create a table which will be automagically destroyed the next */ +/* time any other table is created, and whose keys will be treated */ +/* as case-insensitive */ +int handle2 = Util_TableCreate( UTIL_TABLE_FLAGS_AUTO_DESTROY + | UTIL_TABLE_FLAGS_CASE_INSENSITIVE); + +/* create a table whose keys will be treated as case-insensitive */ +/* (and implicitly destroy the handle2 table) */ +int handle3 = Util_TableCreate(UTIL_TABLE_FLAGS_CASE_INSENSITIVE); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableCreateFromString} +\label{Util-TableCreateFromString} +Creates a new table based on a string argument, which is interpreted +with ``parameter-file'' semantics (the table has the case-insensitive +and auto-destroy flags set) + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int handle = Util_TableCreateFromString(const char *string); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{handle ($\ge 0$)} +a handle to the newly-created table +\end{Result} + +\begin{Parameter}{string} +a pointer to a C-style null-terminated string specifying the table +contents. +\end{Parameter} + +\begin{Discussion} +The present implementation only recognises integer or real values +(not pointer, complex, character, or string), and only scalars +(not arrays). In more detail, the strings recognized are defined by +the following BNF:\\ +\quad +\begin{tabular}{l@{\quad$\rightarrow$\quad}p{9cm}} +string & assign* \\ +assign & whitespace* key = value ;? whitespace* \\ +value & int\_value \\ +value & real\_value \\ +int\_value & contains only characters \verb|+-0123456789| + and is recognized as valid by \verb|sscanf()| with a + \verb|"%d"| format \\ +real\_value & contains one or more characters not in \verb|+-0123456789| + and is recognized as valid by \verb|sscanf()| with a + \verb|"%lf"| format %%%\\ +\end{tabular}\\ +where\\[0ex] +* denotes 0 or more repetitions, and\\ +? denotes optional items, i.e. 0 or 1 repetitions.\\ + +Notice that whitespace separates \verb|key=value| assignments, and +thus that no whitespace may appear within a \verb|key=value| assignment. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableCreate()} +create a table +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSetInt()} +store a \verb|CCTK_INT| value in a table +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSetReal()} +store a \verb|CCTK_REAL| value in a table +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_NO\_MEMORY} +unable to allocate memory +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_INPUT} +invalid input: can't parse input string +\end{Error} +\begin{Error}{\rm other error codes} +this function may also return any error codes returned by +\verb|Util_TableCreate()|, \verb|Util_TableSetInt()|, or +\verb|Util_TableSetReal()|. +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" + +/* simple example */ +CCTK_SomeCactusFunction(..., + Util_TableCreateFromString("order=3"), + ...); + +/* larger example */ + { +int handle = Util_TableCreate( UTIL_TABLE_FLAGS_CASE_INSENSITIVE + | UTIL_TABLE_FLAGS_AUTO_DESTROY ); +Util_TableSetInt(handle, 3, "n"); +Util_TableSetReal(handle, 3.0e-5, "dx"); + +AnotherFunction(..., handle, ...); + +/* equivalent call */ +AnotherFunction(..., Util_TableCreateFromString("n=3 dx=3.0e-5"), ...); + +/* another equivalent call */ +AnotherFunction(..., Util_TableCreateFromString("N=3 DX=3.0E-5"), ...); + } +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableDeleteKey} +\label{Util-TableDeleteKey} +Deletes a specified key/value entry from a table + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int key_exists = Util_TableDeleteKey(int handle, const char *key); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{\rm 0} +ok (key existed before this call, and has now been deleted) +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} +\begin{Parameter}{key} +a pointer to the key (a C-style null-terminated string) +\end{Parameter} + +\begin{Discussion} +This function invalidates any iterators for the table which are +not in the ``null-pointer'' state. +\end{Discussion} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY} +key contains '/' character +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY} +no such key in table +\end{Error} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableDestroy} +\label{Util-TableDestroy} +Destroys a table + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int status = Util_TableDestroy(int handle); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{\rm 0} +ok +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} + +\begin{Discussion} +Of course, this function invalidates any and all iterators for the table. :) +\end{Discussion} + +\begin{SeeAlso}{Util\_TableCreate()} +create a table +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableCreateFromString()} +simplified interface to create a table and set \verb|CCTK_INT| +and/or \verb|CCTK_REAL| values in it based on a parameter-file--like +character string +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" + +/* create a table */ +int handle = Util_TableCreate(UTIL_FLAGS_TABLE_DEFAULT); + +/* do things with the table: put values in it, */ +/* pass its handle to other functions, etc etc */ +/* ... */ + +/* at this point we (and all other functions we */ +/* may call in the future) are done with the table */ +Util_TableDestroy(handle); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableGet*} +\label{Util-TableGet*} +Get the single (1-element array) value, or more generally the first +array element of the value, associated with a specified key in a +key/value table. + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int N_elements = Util_TableGetXxx(int handle, + CCTK_XXX *value, + const char *key); +\end{verbatim} +where \verb|XXX| is one of + \verb|POINTER|, \verb|FN_POINTER|, + \verb|CHAR|, + \verb|INT|, \verb|INT2|, \verb|INT4|, \verb|INT8|, + \verb|REAL|, \verb|REAL4|, \verb|REAL8|, \verb|REAL16|, + \verb|COMPLEX|, \verb|COMPLEX8|, \verb|COMPLEX16|, \verb|COMPLEX32| +(not all of these may be supported on any given system) +\end{Synopsis} + +\begin{Result}{N\_elements} +the number of array elements in the value +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} +\begin{Parameter}{value} +a pointer to where this function should store a copy of the value +(or more generally the first array element of the value) associated +with the specified key, +or NULL pointer to skip storing this +\end{Parameter} +\begin{Parameter}{key} +a pointer to the key (a C-style null-terminated string) +\end{Parameter} + +\begin{Discussion} +Note that it is {\em not\/} an error for the value to actually have +$> 1$ array elements; in this case only the first element is stored. +The rationale for this design is that the caller may know or suspect +that the value is a large array, but may only want the first array +element; in this case this design avoids the caller having to allocate +a large buffer unnecessarily. + +In contrast, it {\em is\/} an error for the value to actually be +an empty (0-length) array, because then there is no ``first array element'' +to get. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableCreateFromString()} +simplified interface to create a table and set \verb|CCTK_INT| +and/or \verb|CCTK_REAL| values in it based on a parameter-file--like +character string +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*Array()} +get an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*String()} +get a character-string value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSet*()} +set a single (1-element array) value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSet*Array()} +set an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSetString()} +set a character-string value +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY} +key contains '/' character +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY} +no such key in table +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_WRONG\_DATA\_TYPE} +value has data type other than \verb|CCTK_TYPE| +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_VALUE\_IS\_EMPTY} +value is an empty (0-element) array +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" + +#define N_DIGITS 5 +static const CCTK_INT pi_digits[N_DIGITS] = {3, 14, 159, 2653, 58979}; + +int N; +CCTK_INT x; +int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT); + +Util_TableSetIntArray(handle, N_DIGITS, pi_digits, "digits of pi"); +Util_TableSetIntArray(handle, 0, pi_digits, "empty array"); + +/* gets N = 5, x = 3 */ +N = Util_TableGetInt(handle, &x, "the answer"); + +/* gets N = UTIL_ERROR_TABLE_VALUE_IS_EMPTY */ +N = Util_TableGetInt(handle, &x, "empty array"); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableGet*Array} +\label{Util-TableGet*Array} +This is a family of functions, one for each Cactus data type, to get +a copy of the value associated with a specified key, and store it +(more accurately, as much of it as will fit) in a specified array + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int N_elements = Util_TableGetXxxArray(int handle, + int N_array, CCTK_XXX array[], + const char *key); +\end{verbatim} +where \verb|XXX| is one of + \verb|POINTER|, \verb|FN_POINTER|, + \verb|CHAR|, + \verb|INT|, \verb|INT2|, \verb|INT4|, \verb|INT8|, + \verb|REAL|, \verb|REAL4|, \verb|REAL8|, \verb|REAL16|, + \verb|COMPLEX|, \verb|COMPLEX8|, \verb|COMPLEX16|, \verb|COMPLEX32| +(not all of these may be supported on any given system) +\end{Synopsis} + +\begin{Result}{N\_elements} +the number of array elements in the value +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} +\begin{Parameter}{N\_array} +the number of array elements in \verb|array[]| +(must be $\ge 0$ if \verb|array != NULL|) +\end{Parameter} +\begin{Parameter}{array} +a pointer to where this function should store (up to \verb|N_array| +elements of) a copy of the value associated with the specified key, +or NULL pointer to skip storing this +\end{Parameter} +\begin{Parameter}{key} +a pointer to the key (a C-style null-terminated string) +\end{Parameter} + +\begin{Discussion} +Note that it is {\em not\/} an error for the value to actually have +$> \verb|N_array|$ array elements; in this case only the first \verb|N_array| +elements are stored. The caller can detect this by comparing the +return value with \verb|N_array|. +The rationale for this design is that the caller may know or suspect +that the value is a large array, but may only want the first few array +elements; in this case this design avoids the caller having to allocate +a large buffer unnecessarily. + +It is also {\em not\/} an error for the value to actually have +$< \verb|N_array|$ array elements; again the caller can detect this by +comparing the return value with \verb|N_array|. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableCreateFromString()} +simplified interface to create a table and set \verb|CCTK_INT| +and/or \verb|CCTK_REAL| values in it based on a parameter-file--like +character string +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*()} +get a single (1-element array) value, +or more generally the first array element of an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*String()} +get a character-string value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSet*()} +set a single (1-element array) value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSet*Array()} +set an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSetString()} +set a character-string value +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY} +key contains '/' character +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_INPUT} +\verb|array != NULL| and \verb|N_array| $< 0$ +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY} +no such key in table +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_WRONG\_DATA\_TYPE} +value has data type other than \verb|CCTK_TYPE| +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" + +#define N_STUFF 3 +static const CCTK_REAL stuff[N_STUFF] = {42.0, 69.0, 105.5}; + +#define N_OUTPUT 2 +CCTK_INT output[N_OUTPUT]; + +int N; +int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT); + +Util_TableSetIntArray(handle, N_STUFF, stuff, "blah blah blah"); + +/* gets N = 3, output[0] = 42.0, output[1] = 69.0 */ +N = Util_TableGetRealArray(handle, N_OUTPUT, output, "blah blah blah"); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableGetString} +\label{Util-TableGetString} +Gets a copy of the character-string value associated with a specified +key in a table, and stores it (more accurately, as much of it as will fit) +in a specified character string + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int length = Util_TableGetString(int handle, + int buffer_length, char buffer[], + const char *key); +\end{verbatim} +\end{Synopsis} + +\begin{ResultNote} +Results are the same as all the other \verb|Util_TableGet|* functions: +\end{ResultNote} +\begin{Result}{length} +the length of the string\\ +(C \verb|strlen()| semantics, \ie{} {\em not\/} including +the terminating null character) +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} +\begin{Parameter}{buffer\_length} +the length (\verb|sizeof()|) of \verb|buffer[]| +(must be $\ge 1$ if \verb|buffer != NULL|) +\end{Parameter} +\begin{Parameter}{buffer} +a pointer to a buffer into which this function should store +(at most \verb|buffer_length-1| characters of) the value, +terminated by a null character as usual for C strings, +or NULL pointer to skip storing this +\end{Parameter} +\begin{Parameter}{key} +a pointer to the key (a C-style null-terminated string) +\end{Parameter} + +\begin{Discussion} +This function assumes that the string is stored as an array of +\verb|CCTK_CHAR|s, {\em not\/} including a terminating null character. +\NewPar +This function differs from \verb|Util_TableGetCharArray()| in two ways: +It explicitly provides a terminating null character for C-style strings, +and it explicitly checks for the string being too long to fit in the buffer +(in which case it returns \verb|UTIL_ERROR_TABLE_STRING_TRUNCATED|). +\end{Discussion} + +\begin{SeeAlso}{Util\_TableCreateFromString()} +simplified interface to create a table and set \verb|CCTK_INT| +and/or \verb|CCTK_REAL| values in it based on a parameter-file--like +character string +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*()} +get a single (1-element array) value, +or more generally the first array element of an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*Array()} +get an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGetCharArray()} +get an array-of-\verb|CCTK_CHAR| value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSet*()} +set a single (1-element array) value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSet*Array()} +set an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSetString()} +set a character-string value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSetCharArray()} +set an array-of-\verb|CCTK_CHAR| value +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY} +key contains '/' character +\end{Error} +\begin{Error}{UTIL\_ERROR\_BAD\_INPUT} +\verb|buffer != NULL| and \verb|buffer_length| $\le 0$ +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY} +no such key in table +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_WRONG\_DATA\_TYPE} +value has data type other than \verb|CCTK_CHAR| +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_STRING\_TRUNCATED} +\quad +\verb|buffer != NULL| and value was truncated to fit in \verb|buffer[]| +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" + +#define N_BUFFER 100 +char buffer[N_BUFFER]; + +int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT); +Util_TableSetString(handle, "relativity", "Einstein"); + +/* get length of string (= 10 here) */ +int length = Util_TableGetString(handle, 0, NULL, "Einstein"); + +/* get null-terminated string into buffer, also returns 10 */ +Util_TableGetString(handle, N_BUFFER, buffer, "Einstein"); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableItAdvance} +\label{Util-TableItAdvance} +Advance a table iterator to the next entry in the table + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int is_nonnull = Util_TableItAdvance(int ihandle); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{\rm 1} +ok (iterator now points to some table entry) +\end{Result} +\begin{Result}{\rm 0} +ok (iterator has just advanced past the last table entry, + and is now in the "null-pointer" state) +\end{Result} + +\begin{Parameter}{ihandle ($\ge 0$)} +handle to the iterator +\end{Parameter} + +\begin{Discussion} +If we view an iterator as an abstraction of a pointer into the table, +then this function is the abstraction of the C \verb|++| operation applied +to the pointer, except that this function automagically sets the iterator +to the "null-pointer" state when it advances past the last table entry. +\NewPar +Note that bad things (garbage results, core dumps) may happen if +you call this function on an iterator which has been invalidated +by a change in the table's contents. +\end{Discussion} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +iterator handle is invalid +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +/* walk through all entries of a table */ +int ihandle; + + for ( ihandle = Util_TableItCreate(handle) ; + Util_TableItQueryIsNull(ihandle) ; + Util_TableItAdvance(ihandle) ) + { + /* do something with the table entry */ + } + +Util_TableItDestroy(ihandle); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableItCreate} +\label{Util-TableItCreate} +Create a new table iterator + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int ihandle = Util_TableItCreate(int handle); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{ihandle ($\ge 0$)} +handle to the iterator +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table over which the iterator should iterate +\end{Parameter} + +\begin{Discussion} +This function creates a new table iterator. The iterator initially +points at the starting table entry. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableItDestroy()} +destroy a table iterator +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +table handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_NO\_MEMORY} +unable to allocate memory +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +/* walk through all entries of a table */ +int ihandle; + + for ( ihandle = Util_TableItCreate(handle) ; + Util_TableItQueryIsNull(ihandle) ; + Util_TableItAdvance(ihandle) ) + { + /* do something with the table entry */ + } + +Util_TableItDestroy(ihandle); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableItDestroy} +\label{Util-TableItDestroy} +Destroy a table iterator + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int status = Util_TableItDestroy(int ihandle); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{\rm 0} +ok +\end{Result} + +\begin{Parameter}{ihandle ($\ge 0$)} +handle to the iterator +\end{Parameter} + +\begin{Discussion} +\end{Discussion} + +\begin{SeeAlso}{Util\_TableItCreate()} +create a table iterator +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +iterator handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_NO\_MEMORY} +unable to allocate memory +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +/* walk through all entries of a table */ +int ihandle; + + for ( ihandle = Util_TableItCreate(handle) ; + Util_TableItQueryIsNull(ihandle) ; + Util_TableItAdvance(ihandle) ) + { + /* do something with the table entry */ + } + +Util_TableItDestroy(ihandle); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableItQueryIsNonNull} +\label{Util-TableItQueryIsNonNull} +Query whether a table iterator is {\em not\/} in the ``null-pointer'' state + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int status = Util_TableItQueryIsNonNull(int ihandle); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{\rm 1} +iterator is {\em not\/} in the ``null-pointer'' state, +\ie{} iterator points to some table entry +\end{Result} +\begin{Result}{\rm 0} +iterator is in the ``null-pointer'' state +\end{Result} + +\begin{Parameter}{ihandle ($\ge 0$)} +handle to the iterator +\end{Parameter} + +\begin{Discussion} +If no errors occur, +\verb|Util_TableItQueryIsNonNull(ihandle)| +is the same as +\verb|1 - Util_TableItQueryIsNull(ihandle)|. +\NewPar +Note that bad things (garbage results, core dumps) may happen if +you call this function on an iterator which has been invalidated +by a change in the table's contents. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableItQueryIsNull()} +query whether a table iterator is in the ``null-pointer'' state +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +iterator handle is invalid +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +/* walk through all entries of a table */ +int ihandle; + + for ( ihandle = Util_TableItCreate(handle) ; + Util_TableItQueryIsNonNull(ihandle) ; + Util_TableItAdvance(ihandle) ) + { + /* do something with the table entry */ + } + +Util_TableItDestroy(ihandle); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableItQueryIsNull} +\label{Util-TableItQueryIsNull} +Query whether a table iterator is in the ``null-pointer'' state + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int status = Util_TableItQueryIsNull(int ihandle); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{\rm 1} +iterator is in the ``null-pointer'' state +\end{Result} +\begin{Result}{\rm 0} +iterator is {\em not\/} in the ``null-pointer'' state, +\ie{} iterator points to some table entry +\end{Result} + +\begin{Parameter}{ihandle ($\ge 0$)} +handle to the iterator +\end{Parameter} + +\begin{Discussion} +If no errors occur, +\verb|Util_TableItQueryIsNull(ihandle)| +is the same as +\verb|1 - Util_TableItQueryIsNonNull(ihandle)|. +\NewPar +Note that bad things (garbage results, core dumps) may happen if +you call this function on an iterator which has been invalidated +by a change in the table's contents. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableItQueryIsNonNull()} +query whether a table iterator is {\em not\/} in the ``null-pointer'' state, +\ie{} whether the iterator points to some table entry +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +iterator handle is invalid +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +/* variant code to walk through all entries of a table */ +int ihandle; + + for ( ihandle = Util_TableItCreate(handle) ; + ! Util_TableItQueryIsNull(ihandle) ; + Util_TableItAdvance(ihandle) ) + { + /* do something with the table entry */ + } + +Util_TableItDestroy(ihandle); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableItQueryKeyValueInfo} +\label{Util-TableItQueryKeyValueInfo} +Query the key and the type and number of elements of the value +corresponding to that key, of the table entry to which an iterator points + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int key_length = + Util_TableItQueryKeyValueInfo(int ihandle, + int key_buffer_length, char key_buffer[], + CCTK_INT *type_code, CCTK_INT *N_elements) +\end{verbatim} +\end{Synopsis} + +\begin{Result}{key\_length} +The string length of the key +(this has C {\t strlen()} semantics, \ie{} it does not +include a terminating null character) +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table iterator +\end{Parameter} +\begin{Parameter}{key\_buffer\_length} +\quad +the length (\verb|sizeof()|) of \verb|key_buffer[]| +(must be $\ge 1$ if \verb|key_buffer != NULL|) +\end{Parameter} +\begin{Parameter}{key\_buffer} +a pointer to a buffer into which this function should store +(at most \verb|key_buffer_length-1| characters of) the key, +terminated by a null character as usual for C strings, +or NULL pointer to skip storing this +\end{Parameter} +\begin{Parameter}{type\_code} +a pointer to where this function should store the value's type code +(one of the \verb|CCTK_VARIABLE_|* constants from \verb|"cctk_Types.h"|), +or a NULL pointer to skip storing this. +\end{Parameter} +\begin{Parameter}{N\_elements} +a pointer to where this function should store +the number of array elements in the value, +or a NULL pointer to skip storing this. +\end{Parameter} + +\begin{Discussion} +The usual use of an iterator is to iterate through all the entries +of a table, calling this function on each entry, then taking further +action based on the results. +\NewPar +Note that bad things (garbage results, core dumps) may happen if +you call this function on an iterator which has been invalidated +by a change in the table's contents. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableQueryValueInfo()} +perform a similar query using the key instead of an iterator +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_ITERATOR\_IS\_NULL} +\quad +iterator is in "null-pointer" state +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_STRING\_TRUNCATED} +\quad +\verb|key_buffer != NULL| and key was truncated to fit in \verb|key_buffer| +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +/* print out all entries in a table */ +/* return 0 for ok, type code for any types we can't handle, */ +/* -ve for other errors */ +#include <stdio.h> +#include <stdlib.h> +#include "util_ErrorCodes.h" +#include "util_Table.h" +#include "cctk.h" + +int print_table(int handle) +{ +int max_key_length, N_key_buffer, ihandle; +char *key_buffer; + +max_key_length = Util_TableQueryMaxKeyLength(handle); +if (max_key_length < 0) + return max_key_length; + +N_key_buffer = max_key_length + 1; +key_buffer = (char *) malloc(N_key_buffer); +if (key_buffer == NULL) + return UTIL_ERROR_NO_MEMORY; + + for ( ihandle = Util_TableItCreate(handle) ; + Util_TableItQueryIsNonNull(ihandle) ; + Util_TableItAdvance(ihandle) ) + { + CCTK_INT type_code, N_elements; + CCTK_INT value_int; + CCTK_REAL value_real; + + Util_TableItQueryKeyValueInfo(int ihandle, + N_key_buffer, key_buffer, + &type_code, &N_elements); + printf("key = \"%s\"\n", key_buffer); + + switch (type_code) + { + case CCTK_VARIABLE_INT: + Util_TableGetInt(handle, &value_int, key_buffer); + printf("value[int] = %d\n", (int)value_int); + break; + case CCTK_VARIABLE_REAL: + Util_TableGetReal(handle, &value_real, key_buffer); + printf("value[real] = %g\n", (double)value_real); + break; + default: + /* we don't know how to handle this type */ + return type_code; + } + } + +Util_TableItDestroy(ihandle); +free(key_buffer); +return 0; +} +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableItQueryTableHandle} +\label{Util-TableItQueryTableHandle} +Query what table a table iterator iterates over + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int handle = Util_TableItQueryTableHandle(int ihandle); +\end{verbatim} +\end{Synopsis} + +\begin{Parameter}{ihandle ($\ge 0$)} +handle to the iterator +\end{Parameter} + +\begin{Result}{handle ($\ge 0$)} +handle to the table over which the iterator iterates +\end{Result} + +\begin{Discussion} +Note that it is always ok to call this function, regardless of +whether or not the iterator is in the ``null-pointer'' state. +\NewPar +It's also ok to call this function even when the iterator has been +invalidated by a change in the table's contents. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableItCreate()} +create an iterator (which iterates over a specified table) +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +iterator handle is invalid +\end{Error} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableItResetToStart} +\label{Util-TableItResetToStart} +Reset a table iterator to point to the starting table entry + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int status = Util_TableItResetToStart(int ihandle); +\end{verbatim} +\end{Synopsis} + +\begin{ResultNote} +Results are the same as calling \verb|Util_TableItQueryIsNonNull()| +on the iterator after the reset: +\end{ResultNote} +\begin{Result}{\rm 1} +iterator is {\em not\/} in the ``null-pointer'' state, +\ie{} iterator points to some table entry +\end{Result} +\begin{Result}{\rm 0} +iterator is in the ``null-pointer'' state +(this happens if and only if the table is empty) +\end{Result} + +\begin{Parameter}{ihandle ($\ge 0$)} +handle to the iterator +\end{Parameter} + +\begin{Discussion} +Note that it is always ok to call this function, regardless of +whether or not the iterator is in the ``null-pointer'' state. +\NewPar +It's also ok to call this function even when the iterator has been +invalidated by a change in the table's contents. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableItSetToNull()} +set an iterator to the ``null-pointer'' state +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableItSetToKey()} +set an iterator to point to a specified table entry +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +iterator handle is invalid +\end{Error} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableItSetToKey} +\label{Util-TableItSetToKey} +set a table iterator to point to a specified table entry + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int status = Util_TableItSetToKey(int ihandle, const char *key); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{\rm 0} +ok +\end{Result} + +\begin{Parameter}{ihandle ($\ge 0$)} +handle to the iterator +\end{Parameter} + +\begin{Discussion} +This function has the same effect as calling \verb|Util_TableItResetToStart()| +followed by calling \verb|Util_TableItAdvance()| zero or more times +to make the iterator point to the desired table entry. However, this +function will typically be more efficient than that sequence. +\NewPar +Note that it is always ok to call this function, regardless of +whether or not the iterator is in the ``null-pointer'' state. +\NewPar +It's also ok to call this function even when the iterator has been +invalidated by a change in the table's contents. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableItResetToStart()} +reset an iterator to point to the starting table entry +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableItSetToNull()} +set a table iterator to the "null-pointer" state +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +iterator handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY} +key contains '/' character +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY} +no such key in table +\end{Error} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableItSetToNull} +\label{Util-TableItSetToNull} +set a table iterator to the "null-pointer" state + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int handle = Util_TableItSetToNull(int ihandle); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{\rm 0} +ok +\end{Result} + +\begin{Parameter}{ihandle ($\ge 0$)} +handle to the iterator +\end{Parameter} + +\begin{Discussion} +Note that it is always ok to call this function, regardless of +whether or not the iterator is already in the ``null-pointer'' state. +\NewPar +It's also ok to call this function even when the iterator has been +invalidated by a change in the table's contents. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableItResetToStart()} +reset an iterator to point to the starting table entry +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableItSetToKey()} +set an iterator to point to a specified table entry +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +iterator handle is invalid +\end{Error} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableQueryFlags} +Queries a table's flags word +\label{Util-TableQueryFlags} + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int flags = Util_TableQueryFlags(int handle); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{flags ($\ge 0$)} +the flags word +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} + +\begin{Discussion} +\end{Discussion} + +\begin{SeeAlso}{Util\_TableCreate()} +create a table (flags word specified explicitly) +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableCreateFromString()} +create a table (flags word specified implicitly) +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include <string.h> +#include "util_ErrorCodes.h" +#include "util_String.h" +#include "util_Table.h" + +/* compare two strings, doing the comparison with the same */ +/* 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); +return (flags & UTIL_TABLE_FLAGS_CASE_INSENSITIVE) + ? Util_StrCmpi(str1, str2) + : strcmp (str1, str2); +} +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableQueryValueInfo} +\label{Util-TableQueryValueInfo} +Queries whether or not a specified key is in the table, and optionally +the type and/or number of elements of the value corresponding to this key + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int key_exists = + Util_TableQueryValueInfo(int handle, + CCTK_INT *type_code, CCTK_INT *N_elements, + const char *key); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{\rm 1} +ok (key is in table) +\end{Result} +\begin{Result}{\rm 0} +ok (no such key in table)\\ +(in this case nothing is stored in \verb|*type_code| and \verb|*N_elements|) +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} +\begin{Parameter}{type\_code} +a pointer to where this function should store the value's type code +(one of the \verb|CCTK_VARIABLE_|* constants from \verb|"cctk_Types.h"|), +or a NULL pointer to skip storing this. +\end{Parameter} +\begin{Parameter}{N\_elements} +a pointer to where this function should store +the number of array elements in the value, +or a NULL pointer to skip storing this. +\end{Parameter} +\begin{Parameter}{key} +a pointer to the key (a C-style null-terminated string) +\end{Parameter} + +\begin{Discussion} +Unlike all the other table query functions, this function returns +0 for ``no such key in table''. The rationale for this design is that +by passing NULL pointers for \verb|type_code| and \verb|N_elements|, this +function is then a Boolean ``is key in table?'' predicate. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableItQueryKeyValueInfo()} +perform a similar query using an iterator instead of the key +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY} +key contains '/' character +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include <stdio.h> +#include <assert.h> +#include "util_ErrorCodes.h" +#include "util_Table.h" + +static const int data[] = {314, 159, 265}; +#define N_DATA (sizeof(data) / sizeof(data[0])) + +CCTK_INT type_code, N_elements; + +/* see whether or not "key" is in table */ +if (Util_TableQueryValueInfo(handle, NULL, NULL, "key")) + { + /* key is in the table */ + } + else { + /* key is not in the table */ + } + +/* put "data" in table as 3-element integer array */ +Util_TableSetIntArray(handle, N_DATA, data, "data"); + +/* query info about "data" value */ +assert( Util_TableQueryValueInfo(handle, + &type_code, &N_elements, + "data") == 1 ); +assert( type_code == CCTK_VARIABLE_INT ); +assert( N_elements == N_DATA ); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableQueryMaxKeyLength} +\label{Util-TableQueryMaxKeyLength} +Queries the maximum key length in a table + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int max_key_length = Util_TableQueryMaxKeyLength(int handle); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{max\_key\_length ($\ge 0$)} +\quad\quad\quad +The string length of the longest key in the table +(this has C {\t strlen()} semantics, \ie{} it does not +include a terminating null character) +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} + +\begin{Discussion} +This function is useful if you're going to iterate through a table, +and you want to allocate a buffer which is guaranteed to be big enough +to hold any key in the table. +\end{Discussion} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include <stdlib.h> +#include "util_ErrorCodes.h" +#include "util_Table.h" +#include "cctk.h" + +int max_key_length = Util_TableQueryMaxKeyLength(handle); +int N_buffer = max_key_length + 1; +char *const buffer = (char *) malloc(N_buffer); +if (buffer == NULL) + { + CCTK_WARN(-1, "couldn't allocate memory for table key buffer!"); + abort(); /* CCTK_Abort() would be better */ + /* if we have a cGH* available */ + } + +/* now buffer is guaranteed to be */ +/* big enough for any key in the table */ +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableQueryNKeys} +\label{Util-TableQueryNKeys} +Queries the number of key/value entries in a table + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int N_Keys = Util_TableQueryNKeys(int handle); +\end{verbatim} +\end{Synopsis} + +\begin{Result}{N\_Keys ($\ge 0$)} +the number of key/value entries in the table +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} + +\begin{Discussion} +\end{Discussion} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableSet*} +\label{Util-TableSet*} +This is a family of functions, one for each Cactus data type, +to set the value associated with a specified key to be a specified +single (1-element array) value + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int status = Util_TableSetXxx(int handle, + CCTK_XXX value, + const char *key); +\end{verbatim} +where \verb|XXX| is one of + \verb|POINTER|, \verb|FN_POINTER|, + \verb|CHAR|, + \verb|INT|, \verb|INT2|, \verb|INT4|, \verb|INT8|, + \verb|REAL|, \verb|REAL4|, \verb|REAL8|, \verb|REAL16|, + \verb|COMPLEX|, \verb|COMPLEX8|, \verb|COMPLEX16|, \verb|COMPLEX32| +(not all of these may be supported on any given system) +\end{Synopsis} + +\begin{Result}{\rm 1} +ok (key was already in table before this call, old value was replaced)\\ + (it doesn't matter what the old value's \verb|type_code| and + \verb|N_elements| were, \ie{} these do {\em not\/} have to match + the new value) +\end{Result} +\begin{Result}{\rm 0} +ok (key was not in table before this call) +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} +\begin{Parameter}{value} +the value to be associated with the key +\end{Parameter} +\begin{Parameter}{key} +a pointer to the key (a C-style null-terminated string) +\end{Parameter} + +\begin{Discussion} +The value is stored as a 1-element array. +\NewPar +This function invalidates any iterators for the table which are +not in the ``null-pointer'' state. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableCreateFromString()} +simplified interface to create a table and set \verb|CCTK_INT| +and/or \verb|CCTK_REAL| values in it based on a parameter-file--like +character string +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*()} +get a single (1-element array) value, +or more generally the first array element of an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*Array()} +get an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*String()} +get a character-string value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSet*Array()} +set an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSetString()} +set a character-string value +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY} +key contains '/' character +\end{Error} +\begin{Error}{UTIL\_ERROR\_NO\_MEMORY} +unable to allocate memory +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include <math.h> +#include "util_ErrorCodes.h" +#include "util_Table.h" + +CCTK_COMPLEX16 z; +int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT); + +Util_TableSetInt(handle, 42, "the answer"); +Util_TableSetReal(handle, 299792458.0, "speed of light"); + +z.Re = cos(0.37); z.Im = sin(0.37); +Util_TableSetComplex16(handle, z, "my complex number"); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableSet*Array} +\label{Util-TableSet*Array} +This is a family of functions, one for each Cactus data type, +to set the value associated with a specified key to be a copy +of a specified array + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int status = Util_TableSetXxxArray(int handle, + int N_elements, + const CCTK_XXX array[], + const char *key); +\end{verbatim} +where \verb|XXX| is one of + \verb|POINTER|, \verb|FN_POINTER|, + \verb|CHAR|, + \verb|INT|, \verb|INT2|, \verb|INT4|, \verb|INT8|, + \verb|REAL|, \verb|REAL4|, \verb|REAL8|, \verb|REAL16|, + \verb|COMPLEX|, \verb|COMPLEX8|, \verb|COMPLEX16|, \verb|COMPLEX32| +(not all of these may be supported on any given system) +\end{Synopsis} + +\begin{Result}{\rm 1} +ok (key was already in table before this call, old value was replaced)\\ + (it doesn't matter what the old value's \verb|type_code| and + \verb|N_elements| were, \ie{} these do {\em not\/} have to match + the new value) +\end{Result} +\begin{Result}{\rm 0} +ok (key was not in table before this call) +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} +\begin{Parameter}{N\_elements ($\ge 0$)} +the number of array elements in \verb|array[]| +\end{Parameter} +\begin{Parameter}{array} +a pointer to the array (a copy of which) is to be associated with the key +\end{Parameter} +\begin{Parameter}{key} +a pointer to the key (a C-style null-terminated string) +\end{Parameter} + +\begin{Discussion} +Note that empty (0-element) arrays are ok. +\NewPar +This function invalidates any iterators for the table which are +not in the ``null-pointer'' state. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableCreateFromString()} +simplified interface to create a table and set \verb|CCTK_INT| +and/or \verb|CCTK_REAL| values in it based on a parameter-file--like +character string +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*()} +get a single (1-element array) value, +or more generally the first array element of an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*Array()} +get an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*String()} +get a character-string value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSet*()} +set a single (1-element array) value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSetString()} +set a character-string value +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY} +key contains '/' character +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_INPUT} +\verb|N_elements| $< 0$ +\end{Error} +\begin{Error}{UTIL\_ERROR\_NO\_MEMORY} +unable to allocate memory +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" + +#define N_DIGITS 5 +static const CCTK_INT pi_digits[N_DIGITS] = {3, 14, 159, 2653, 58979}; +int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT); + +Util_TableSetIntArray(handle, N_DIGITS, pi_digits, "digits of pi"); +\end{verbatim} +\end{Example} +\end{FunctionDescription} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{FunctionDescription}{Util\_TableSetString} +\label{Util-TableSetString} +Sets the value associated with a specified key in a table, to be +a copy of a specified C-style null-terminated character string + +\begin{Synopsis}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" +int status = Util_TableSetString(int handle, + const char *string, + const char *key); +\end{verbatim} +\end{Synopsis} + +\begin{ResultNote} +Results are the same as all the other \verb|Util_TableSet|* functions: +\end{ResultNote} +\begin{Result}{\rm 1} +ok (key was already in table before this call, old value was replaced)\\ + (it doesn't matter what the old value's \verb|type_code| and + \verb|N_elements| were, \ie{} these do {\em not\/} have to match + the new value) +\end{Result} +\begin{Result}{\rm 0} +ok (key was not in table before this call) +\end{Result} + +\begin{Parameter}{handle ($\ge 0$)} +handle to the table +\end{Parameter} +\begin{Parameter}{string} +a pointer to the string (a C-style null-terminated string) +\end{Parameter} +\begin{Parameter}{key} +a pointer to the key (a C-style null-terminated string) +\end{Parameter} + +\begin{Discussion} +The string is stored as an array of \verb|strlen(string)| +\verb|CCTK_CHAR|s. It does {\em not\/} include a terminating +null character. +\NewPar +This function is very similar to \verb|Util_TableSetCharArray()|. +\NewPar +This function invalidates any iterators for the table which are +not in the ``null-pointer'' state. +\end{Discussion} + +\begin{SeeAlso}{Util\_TableCreateFromString()} +simplified interface to create a table and set \verb|CCTK_INT| +and/or \verb|CCTK_REAL| values in it based on a parameter-file--like +character string +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*()} +get a single (1-element array) value, +or more generally the first array element of an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*Array()} +get an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableGet*String()} +get a character-string value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSetCharArray()} +get an array-of-\verb|CCTK_CHAR| value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSet*()} +set a single (1-element array) value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSet*Array()} +set an array value +\end{SeeAlso} +\begin{SeeAlso}{Util\_TableSetCharArray()} +set an array-of-\verb|CCTK_CHAR| value +\end{SeeAlso} + +\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} +handle is invalid +\end{Error} +\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY} +key contains '/' character +\end{Error} +\begin{Error}{UTIL\_ERROR\_NO\_MEMORY} +unable to allocate memory +\end{Error} + +\begin{Example}{C} +\begin{verbatim} +#include "util_ErrorCodes.h" +#include "util_Table.h" + +static const CCTK_CHAR array[] + = {'r', 'e', 'l', 'a', 't', 'i', 'v', 'i', 't', 'y'}; +#define N_ARRAY (sizeof(array) / sizeof(array[0])) +int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT); + +Util_TableSetString(handle, "relativity", "Einstein"); + +/* this produces the same table entry as the Util_TableSetString() */ +Util_TableSetCharArray(handle, N_ARRAY, array, "Einstein"); +\end{verbatim} +\end{Example} +\end{FunctionDescription} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \end{cactuspart} |