Added SpaceMask_GetMaskBitsList() function, which returns an ordered

list of all the bitmasks associated with each state of a given type.
Also allowed for passing a NULL as the list of state names on registry,
in which case the mask states are allocated but not named.
These additions make it easier to allocate a mask bitfield of a size
that might only be known at runtime.
More routines for working with mask states as integers might be useful
in the future.


git-svn-id: http://svn.cactuscode.org/arrangements/CactusNumerical/SpaceMask/trunk@31 a491c6a4-70bf-4b89-8b36-d6c0cb1f094e

1 files changed, 32 insertions, 7 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index d6adc5d..2fb7e76 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -83,7 +83,7 @@ int SpaceMask\_RegisterType(const char* \emph{type\_name},
 \begin{description}
   \item[\emph{type\_name}] The name of the new type to be registered;
   \item[\emph{nstates}] The number of states in the new type;
-  \item[\emph{state\_list}] A list of names, one for each state.
+  \item[\emph{state\_list}] A list of names, one for each state, or NULL.
 \end{description}
 }
 }
@@ -96,6 +96,13 @@ function returns a $-1$ if the required states cannot be allocated
 (for example, if there are not enough free bits remaining in the
 mask), otherwise it returns $0$.
 
+It is possible to allocate a portion of the mask without assigning
+names to any of the states by passing NULL as the \emph{state\_list}.
+This is useful when some integer number of states is required for a
+given type, but the number of states and appropriate names are not
+known at compile time. States which are allocated in this way can be
+accessed using the \texttt{SpaceMask\_GetStateBitsList()}.
+
 New states can be added to an already allocated type using the
 function:
 
@@ -199,12 +206,31 @@ bitmask corresponding to the given type or state. For example, if a
 given type uses three bits of the mask, the returned value could be
 the integer corresponding to the bitfield $001110000$\ldots, where the
 location of $1$s indicates the bits which have been allocated to the
-given type. A return value of $-1$ indicates that the bitmask could
+given type. A return value of $0$ indicates that the bitmask could
 not be determined for some reason (for example, the requested state
-was not previously registered)\footnote{Note that a potential
-ambiguity arises here, in that if the full mask is allocated to a
-single type, then $-1$ is a valid state. It is assumed that this
-eventuality won't arise in practice.}.
+was not previously registered).
+
+All of the state masks allocated for a given type can be retrieved
+using the following function:
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+CCTK\_INT* SpaceMask\_GetStateBitsList(const char* \emph{type\_name})
+}\\
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{type\_name}] The type for which the bitmask is to be
+  determined.
+\end{description}
+}}
+
+The return value is a list of integers, with a length corresponding to
+the number of states of the given type. Each of the entries is a
+bitmask which identifies the state. List entries are returned in the
+order in which they were originally assigned. This allows for a simple
+correspondence between states and integers (given by the index of the
+list entry). \emph{A fortran wrapper does not currently exist for this
+functionality.}
 
 The following macros have been defined for fast setting and checking
 of the mask by direct bitwise operations:
@@ -385,7 +411,6 @@ of the mask required grid symmetries to work for integer grid
 functions. This was done by Thomas Radke. Peter Diener helped with the
 coding of the Fortran90 bitwise operators.
 
-\pagebreak
 \section{Appendix}
 
 \subsection{Example: C code}\label{app:eg_C}