From cdd316e2675c02ce3090ae83b4d7c92c8350db1a Mon Sep 17 00:00:00 2001
From: jthorn <jthorn@df1f8a13-aa1d-4dd4-9681-27ded5b42416>
Date: Sat, 23 Mar 2002 21:43:03 +0000
Subject: fix examples to initialize pointer arrays in ways that are valid in
 C, not just in C++

git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/LocalInterp/trunk@16 df1f8a13-aa1d-4dd4-9681-27ded5b42416
---
 doc/documentation.tex | 133 +++++++++++++++++++++++++++++++++++---------------
 1 file changed, 94 insertions(+), 39 deletions(-)

(limited to 'doc/documentation.tex')

diff --git a/doc/documentation.tex b/doc/documentation.tex
index d7aa257..317c896 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -9,6 +9,9 @@
 
 \def\defn#1{{\bf #1}}
 
+% nicely typeset "C++" (adapted from a comp.lang.C++ FAQ entry)
+\def\Cplusplus{\hbox{C\hspace{-.05em}\raisebox{.4ex}{\tiny\bf ++}}}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \begin{document}
@@ -848,17 +851,25 @@ implementation.
 
 \subsection{A Simple Example of {\tt CCTK\_InterpLocalUniform} Usage}
 
-Here's a simple example of interpolating a \verb|CCTK_REAL| and a
+Here's a simple example in C, of interpolating a \verb|CCTK_REAL| and a
 \verb|CCTK_COMPLEX| $10 \times 20$ 2-D array, at 5 interpolation points,
 using cubic interpolation.
 
+Note that since C allows arrays to be initialized only if the
+initializer values are compile-time constants, we have to declare the
+\verb|interp_coords[]|, \verb|input_arrays[]|, and \verb|output_arrays[]|
+arrays as non-\verb|const|, and set their values with ordinary (run-time)
+assignment statements.  In \Cplusplus, there's no restriction on
+initializer values, so we could declare the arrays \verb|const| and
+initialize them as part of their declarations.
+
 \begin{verbatim}
 #define N_DIMS   2
 #define N_INTERP_POINTS   5
 #define N_INPUT_ARRAYS    2
 #define N_OUTPUT_ARRAYS   2
 
-/* (x,y,z) coordinates of data grid points */
+/* (x,y) coordinates of data grid points */
 #define X_ORIGIN   ...
 #define X_DELTA    ...
 #define Y_ORIGIN   ...
@@ -866,11 +877,10 @@ using cubic interpolation.
 const CCTK_REAL origin[N_DIMS] = { X_ORIGIN, Y_ORIGIN };
 const CCTK_REAL delta [N_DIMS] = { X_DELTA,  Y_DELTA  };
 
-/* (x,y,z) coordinates of interpolation points */
+/* (x,y) coordinates of interpolation points */
 const CCTK_REAL interp_x[N_INTERP_POINTS];
 const CCTK_REAL interp_y[N_INTERP_POINTS];
-const void *const interp_coords[N_DIMS]
-        = { (const void *) interp_x, (const void *) interp_y };
+const void *interp_coords[N_DIMS];              /* see note above */
 
 /* input arrays */
 /* ... note Cactus uses Fortran storage ordering, i.e. X is contiguous */
@@ -881,16 +891,14 @@ const CCTK_COMPLEX input_complex[NY][NX];
 const CCTK_INT input_array_dims[N_DIMS] = { NX, NY };
 const CCTK_INT input_array_type_codes[N_INPUT_ARRAYS]
         = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
-const void *const input_arrays[N_INPUT_ARRAYS]
-        = { (const void *) input_real, (const void *) input_complex };
+const void *input_arrays[N_INPUT_ARRAYS];       /* see note above */
 
 /* output arrays */
 CCTK_REAL    output_real   [N_INTERP_POINTS];
 CCTK_COMPLEX output_complex[N_INTERP_POINTS];
 const CCTK_INT output_array_type_codes[N_OUTPUT_ARRAYS]
         = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
-void *const output_arrays[N_OUTPUT_ARRAYS]
-        = { (void *) output_real, (void *) output_complex };
+void *output_arrays[N_OUTPUT_ARRAYS];           /* see note above */
 
 int operator_handle, param_table_handle;
 operator_handle = CCTK_InterpHandle("my interpolation operator");
@@ -900,6 +908,15 @@ param_table_handle = Util_TableCreateFromString("order=3");
 if (param_table_handle < 0)
         CCTK_WARN(-1, "can't create parameter table!");
 
+/* initialize the rest of the parameter arrays */
+interp_coords[0] = (const void *) interp_x;
+interp_coords[1] = (const void *) interp_y;
+input_arrays [0] = (const void *) input_real;
+input_arrays [1] = (const void *) input_complex;
+output_arrays[0] = (      void *) output_real;
+output_arrays[1] = (      void *) output_complex;
+
+/* do the actual interpolation, and check for error returns */
 if (CCTK_InterpLocalUniform(N_DIMS,
                             operator_handle, param_table_handle,
                             origin, delta,
@@ -923,7 +940,18 @@ if (CCTK_InterpLocalUniform(N_DIMS,
 
 Consider the problem described earlier: the computation of all the
 2nd~derivatives of the 3-metric at a set of interpolation points on
-a 2-sphere.  Here's how we could do this in C:
+a 2-sphere.  This example shows how we could do this in C.
+
+[Since we're not using \Cplusplus, we again declare the pointer arrays
+non-\verb|const|, and ``initialize'' them with ordinary (run-time)
+assignment statements.  However, in this example, for greater clarity
+we place these assignment statements right after the declarations.
+Since C allows declarations only at the start of a \verb|{ }| block,
+not in the middle of a block, we nest the rest of the program in extra
+blocks (with the \verb|{ }| indented 2 spaces to distinguish them from
+``normal'' \verb|{ }| pairs) to allow for further declarations.
+The reader will have to decide whether this style is more or less ugly
+than separating the declarations and initializations of the pointer arrays.]
 \begin{verbatim}
 #define N_DIMS        3
 
@@ -932,11 +960,12 @@ a 2-sphere.  Here's how we could do this in C:
 const CCTK_REAL interp_x[N_INTERP_POINTS],
                 interp_y[N_INTERP_POINTS],
                 interp_z[N_INTERP_POINTS];
-const void *const interp_coords[N_DIMS]
-        = { (const void *) interp_x,
-            (const void *) interp_y,
-            (const void *) interp_z };
+const void *interp_coords[N_DIMS];              /* see note above */
+interp_coords[0] = (const void *) interp_x;
+interp_coords[1] = (const void *) interp_y;
+interp_coords[2] = (const void *) interp_z;
 
+  {
 /* dimensions of the data grid */
 #define NX   30
 #define NY   40
@@ -954,11 +983,15 @@ const CCTK_INT input_array_type_codes[N_INPUT_ARRAYS]
         = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_REAL, CCTK_VARIABLE_REAL,
                                 CCTK_VARIABLE_REAL, CCTK_VARIABLE_REAL,
                                                     CCTK_VARIABLE_REAL };
-const void *const input_arrays[N_INPUT_ARRAYS]
-        = { (const void *) gxx, (const void *) gxy, (const void *) gxz,
-                                (const void *) gyy, (const void *) gyz,
-                                                    (const void *) gzz };
-
+const void *input_arrays[N_INPUT_ARRAYS];       /* see note above */
+input_arrays[0] = (const void *) gxx;
+input_arrays[1] = (const void *) gxy;
+input_arrays[2] = (const void *) gxz;
+input_arrays[3] = (const void *) gyy;
+input_arrays[4] = (const void *) gyz;
+input_arrays[5] = (const void *) gzz;
+
+  {
 /* output arrays */
 #define N_OUTPUT_ARRAYS 36
 CCTK_REAL
@@ -999,26 +1032,45 @@ const CCTK_INT output_array_type_codes[N_OUTPUT_ARRAYS]
        CCTK_VARIABLE_REAL, CCTK_VARIABLE_REAL, CCTK_VARIABLE_REAL,
                            CCTK_VARIABLE_REAL, CCTK_VARIABLE_REAL,
                                                CCTK_VARIABLE_REAL };
-void *const output_arrays[N_OUTPUT_ARRAYS]
-   = { (void *) dxx_gxx, (void *) dxy_gxx, (void *) dxz_gxx,
-                         (void *) dyy_gxx, (void *) dyz_gxx,
-                                           (void *) dzz_gxx,
-       (void *) dxx_gxy, (void *) dxy_gxy, (void *) dxz_gxy,
-                         (void *) dyy_gxy, (void *) dyz_gxy,
-                                           (void *) dzz_gxy,
-       (void *) dxx_gxz, (void *) dxy_gxz, (void *) dxz_gxz,
-                         (void *) dyy_gxz, (void *) dyz_gxz,
-                                           (void *) dzz_gxz,
-       (void *) dxx_gyy, (void *) dxy_gyy, (void *) dxz_gyy,
-                         (void *) dyy_gyy, (void *) dyz_gyy,
-                                           (void *) dzz_gyy,
-       (void *) dxx_gyz, (void *) dxy_gyz, (void *) dxz_gyz,
-                         (void *) dyy_gyz, (void *) dyz_gyz,
-                                           (void *) dzz_gyz,
-       (void *) dxx_gzz, (void *) dxy_gzz, (void *) dxz_gzz,
-                         (void *) dyy_gzz, (void *) dyz_gzz,
-                                           (void *) dzz_gzz };
-
+void *output_arrays[N_OUTPUT_ARRAYS];           /* see note above */
+output_arrays[ 0] =      (void *) dxx_gxx;
+output_arrays[ 1]  =     (void *) dxy_gxx;
+output_arrays[ 2]   =    (void *) dxz_gxx;
+output_arrays[ 3]    =   (void *) dyy_gxx;
+output_arrays[ 4]     =  (void *) dyz_gxx;
+output_arrays[ 5]      = (void *) dzz_gxx;
+output_arrays[ 6] =      (void *) dxx_gxy;
+output_arrays[ 7]  =     (void *) dxy_gxy;
+output_arrays[ 8]   =    (void *) dxz_gxy;
+output_arrays[ 9]    =   (void *) dyy_gxy;
+output_arrays[10]     =  (void *) dyz_gxy;
+output_arrays[11]      = (void *) dzz_gxy;
+output_arrays[12] =      (void *) dxx_gxz;
+output_arrays[13]  =     (void *) dxy_gxz;
+output_arrays[14]   =    (void *) dxz_gxz;
+output_arrays[15]    =   (void *) dyy_gxz;
+output_arrays[16]     =  (void *) dyz_gxz;
+output_arrays[17]      = (void *) dzz_gxz;
+output_arrays[18] =      (void *) dxx_gyy;
+output_arrays[19]  =     (void *) dxy_gyy;
+output_arrays[20]   =    (void *) dxz_gyy;
+output_arrays[21]    =   (void *) dyy_gyy;
+output_arrays[22]     =  (void *) dyz_gyy;
+output_arrays[23]      = (void *) dzz_gyy;
+output_arrays[24] =      (void *) dxx_gyz;
+output_arrays[25]  =     (void *) dxy_gyz;
+output_arrays[26]   =    (void *) dxz_gyz;
+output_arrays[27]    =   (void *) dyy_gyz;
+output_arrays[28]     =  (void *) dyz_gyz;
+output_arrays[29]      = (void *) dzz_gyz;
+output_arrays[30] =      (void *) dxx_gzz;
+output_arrays[31]  =     (void *) dxy_gzz;
+output_arrays[32]   =    (void *) dxz_gzz;
+output_arrays[33]    =   (void *) dyy_gzz;
+output_arrays[34]     =  (void *) dyz_gzz;
+output_arrays[35]      = (void *) dzz_gzz;
+
+  {
 /* integer codes to specify the derivatives */
 /* (for best efficiency we group all operations on a given input together) */
 const CCTK_INT operand_indices[N_OUTPUT_ARRAYS]
@@ -1070,6 +1122,9 @@ if (CCTK_InterpLocalUniform(N_DIMS,
                                output_array_type_codes,
                                output_arrays) < 0)
         CCTK_WARN(-1, "error return from interpolator!");
+  }
+  }
+  }
 \end{verbatim}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-- 
cgit v1.2.3

