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

2 files changed, 88 insertions, 12 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}
diff --git a/src/MaskUtils.c b/src/MaskUtils.c
index 784f5b0..1394267 100644
--- a/src/MaskUtils.c
+++ b/src/MaskUtils.c
@@ -229,9 +229,19 @@ SpaceMask_setup_new_type(CCTK_INT new_bits, const char* type_name,
   new_type->state_list =
     (SpaceMask_State**) malloc (nstates*sizeof(SpaceMask_State*));
 
-  for (j=0; j<nstates; ++j)
-    new_type->state_list[j] = SpaceMask_setup_new_state(state_mask[j],
-							state_list[j]);
+  if (state_list==NULL)
+    {
+      for (j=0; j<nstates; ++j)
+	new_type->state_list[j] = SpaceMask_setup_new_state(state_mask[j],
+							    NULL);
+    }
+  else
+    {
+      for (j=0; j<nstates; ++j)
+	new_type->state_list[j] = SpaceMask_setup_new_state(state_mask[j],
+							    state_list[j]);
+    }
+
   return new_type;
 }
 
@@ -292,7 +302,7 @@ SpaceMask_RegisterType(const char* type_name, int nstates,
   CCTK_INT new_bits;
   CCTK_INT* state_mask;
   int bit_nbr;
-
+ 
   bit_nbr = SpaceMask_get_bit_nbr(nstates);
   new_bits = SpaceMask_get_free_bits(bit_nbr);
 
@@ -454,6 +464,46 @@ SpaceMask_GetStateBits(const char* type_name, const char* state_name)
 }
 
 /*@@
+  @routine    SpaceMask_GetStateBitsList
+  @author     Denis Pollney
+  @date       25 May 2003
+  @desc 
+              Returns a list of all of the state masks allocated
+	      for a given type. The number of elements in the list
+	      is equal to the number of states of the type.
+	      If the type name is not recognised, NULL is returned.
+  @enddesc 
+@@*/
+
+CCTK_INT*
+SpaceMask_GetStateBitsList(const char* type_name)
+{
+  SpaceMask_Type* type;
+  CCTK_INT* state_bits_list;
+  int i, j;
+
+  for (i=0; i<spacemask_registry->ntypes; ++i)
+    {
+      if (!strcmp(spacemask_registry->type_list[i]->name, type_name))
+	{
+	  type = spacemask_registry->type_list[i];
+	  state_bits_list = (CCTK_INT*) 
+	    malloc (sizeof(CCTK_INT)*(type->nstates));
+
+	  for (j=0; j<type->nstates; ++j)
+	    state_bits_list[j] = type->state_list[j]->bitmask;
+
+	  return state_bits_list;
+	}
+    }
+
+  CCTK_VInfo (CCTK_THORNSTRING, 
+	      "Requested type \"%s\" could not be found\n", type_name);
+
+  return NULL;
+}
+
+/*@@
   @routine    SpaceMask_SetState
   @author     Denis Pollney
   @date       15 October 2002
@@ -484,7 +534,7 @@ SpaceMask_SetState(CCTK_INT* mask, int point, const char* type_name, const char*
   @enddesc 
 @@*/
 
-int
+CCTK_INT
 SpaceMask_CheckState(const CCTK_INT* mask, int point, const char* type_name, const char* state)
 {
   CCTK_INT type_bits;
@@ -496,6 +546,7 @@ SpaceMask_CheckState(const CCTK_INT* mask, int point, const char* type_name, con
   return SpaceMask_CheckStateBits(mask, point, type_bits, state_bits);
 }
 
+
 /********************************************************************
  *********************  Fortran Wrappers  ***************************
  ********************************************************************/