Running Sum (Example 1)

The first example of RSUM is very simple. Here is a simple "Reference Manual" style description of it:

RSUM1

Compute a running sum on the array input. The result is a floating point array of the same dimensions.

Calling Sequence

Result = RSUM1(Array)

Arguments

Array

Array for which a running sum will be computed.

This is a minimal design that lacks some important characteristics that IDL system routines usually embody:

We will improve on this design in our subsequent attempts. The code to implement RSUM1 is shown in the following figure. The line numbers are not part of the code and are present to make the discussion easier to follow. Each line of this routine is discussed below:

Table 15-3: Code for IDL_rsum1()

C 
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 

IDL_VPTR IDL_rsum1(int argc, IDL_VPTR argv[]) 
{ 
  IDL_VPTR v; 
  IDL_VPTR r; 
  float *f_src; 
  float *f_dst; 
  IDL_MEMINT n; 
  
  
  v = argv[0]; 
  if (v->type != IDL_TYP_FLOAT) 
    IDL_Message(IDL_M_NAMED_GENERIC, IDL_MSG_LONGJMP, 
                "argument must be float"); 
  IDL_ENSURE_ARRAY(v); 
  IDL_EXCLUDE_FILE(v); 
  
  f_dst = (float *)  
    IDL_VarMakeTempFromTemplate(v, IDL_TYP_FLOAT, 
                                (IDL_StructDefPtr) 0, &r, FALSE); 
  f_src = (float *) v->value.arr->data; 
  n = v->value.arr->n_elts - 1; 
  *f_dst++ = *f_src++;		/* First element */ 
  for (; n--; f_dst++) *f_dst = *(f_dst - 1) + *f_src++; 
  
  return r; 
}

1

The standard signature for an IDL system function that does not accept keywords.

3

This variable is used to access the input argument in a convenient way.

4

This IDL_VPTR will be used to return the result.

5–6

As the running sum is computed, f_src will point at the input data and f_dst will point at the output data.

7

The number of elements in the input.

10

Obtain the input variable pointer from argv[0].

11

If the input is not single precision floating point, throw an error and quit. This is overly rigid. Real IDL routines would attempt to either type convert the input or do the computation in the input type.

14

This version can only handle arrays. If the user passes a scalar, it throws an error.

15

This routine cannot handle ASSOC file variables. Most IDL routines exclude such variables as they do not contain any data to work with. ASSOC variable data usually comes into a routine as the result of an expression that yields a temporary variable (e.g. TMP = RSUM(MY_ASSOC_VAR(2))).

17

Create a single precision floating point temporary variable of the same size as the input variable and get a pointer to its data area.

20

Get a pointer to the data area of the input variable. At this point we know this variable is always a floating point array.

21

The number of data elements in the input.

22-23

The running sum computation.

25

Return the result.

Running Sum (Example 2)

In our second example of RSUM, we improve on version 1 in several ways:

As always, the first step in writing a system routine is to write a simple description of its interface and intended behavior:

RSUM2

Compute a running sum on the input. The result is a floating point variable with the same structure.

Calling Sequence

Result = RSUM2(Input)

Arguments

Input

Scalar or array data of any numeric type for which a running sum will be computed.

The following is the code for RSUM2:

Table 15-4: Code for IDL_rsum2().

C 
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 

IDL_VPTR IDL_rsum2(int argc, IDL_VPTR argv[]) 
{ 
  IDL_VPTR v; 
  IDL_VPTR r; 
  float *f_src; 
  float *f_dst; 
  IDL_MEMINT n; 
  
  
  v = IDL_BasicTypeConversion(1, argv, IDL_TYP_FLOAT); 
  /* IDL_BasicTypeConversion calls IDL_ENSURE_SIMPLE, so 
     skip it here. */ 
  IDL_VarGetData(v, &n, (char **) &f_src, FALSE); 
  
  /* Get a result var, reusing the input if possible */ 
  if (v->flags & V_TEMP) { 
    r = v; 
    f_dst = f_src; 
  } else { 
    f_dst = (float *)  
      IDL_VarMakeTempFromTemplate(v, IDL_TYP_FLOAT,  
                                  (IDL_StructDefPtr) 0, &r, FALSE); 
  } 
  
  *f_dst++ = *f_src++;		/* First element */ 
  n--; 
  for (; n--; f_dst++) *f_dst = *(f_dst - 1) + *f_src++; 
  
  return r; 
}

Discussion of the code for the improvements introduced in this version follow:

10

If the input has the wrong type, obtain one of the right type. If it was already of the correct type, IDL_BasicTypeConversion() will simply return the input value without allocating a temporary variable. Hence, no explicit check for that is required. Also, if the input argument cannot be converted to the desired type (e.g. it is a structure or file variable) IDL_BasicTypeConversion() will throw an error. Hence, we know that the result from this function will be what we want without requiring any further checking.

13

IDL_VarGetData() is a more elegant way to obtain a pointer to variable data along with a count of elements. A further benefit is that it automatically handles scalar variables which removes the restriction from RSUM1.

15–23

If the input variable is a temporary, we will do the computation in place and return the input. Otherwise, we create a temporary variable of the desired type to be the result.

Note that if IDL_BasicTypeConversion() returned a pointer to anything other than the passed in value of argv[0], that value will be a temporary variable which will then be turned into the function result by this code. Hence, we never free the value from IDL_BasicTypeConversion().

Running Sum (Example 3)

RSUM2 is a big improvement over RSUM1, but it still suffers from the fact that all computation is done in a single data type. A real IDL system routine always tries to perform computations in the most significant type presented by its arguments. In a single argument case like RSUM, that would mean doing computations in the input data type whatever that might be. Our final version, RSUM3, resolves this shortcoming.

RSUM3

Compute a running sum on the input. The result is a variable with the same type and structure as the input.

Calling Sequence

Result = RSUM3(Input)

Arguments

Input

Scalar or array data of any numeric type for which a running sum will be computed.

The code for RSUM3 is given in the following figure. Discussion of the code for the improvements introduced in this version follow:

Table 15-5: Code for IDL_rsum3 

C 
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 

cx_public IDL_VPTR IDL_rsum3(int argc, IDL_VPTR argv[]) 
{ 
   IDL_VPTR v, r; 
   union { 
     char *sc;                 /* Standard char */ 
     UCHAR *c;                 /* IDL_TYP_BYTE */ 
     IDL_INT *i;               /* IDL_TYP_INT */ 
     IDL_UINT *ui;             /* IDL_TYP_UINT */ 
     IDL_LONG *l;              /* IDL_TYP_LONG */ 
     IDL_ULONG *ul;            /* IDL_TYP_ULONG */ 
     IDL_LONG64 *l64;          /* IDL_TYP_LONG64 */ 
     IDL_ULONG64 *ul64;        /* IDL_TYP_ULONG64 */ 
     float *f;                 /* IDL_TYP_FLOAT */ 
     double *d;                /* IDL_TYP_DOUBLE */ 
     IDL_COMPLEX *cmp;         /* IDL_TYP_COMPLEX */ 
     IDL_DCOMPLEX *dcmp;       /* IDL_TYP_DCOMPLEX */ 
} src, dst; 
IDL_LONG n; 
  
  
v = argv[0]; 
if (v->type == IDL_TYP_STRING) 
  v = IDL_BasicTypeConversion(1, argv, IDL_TYP_FLOAT); 
IDL_VarGetData(v, &n, &(src.sc), TRUE); 
n--;                           /* First is a special case */ 
  
/* Get a result var, reusing the input if possible */ 
if (v->flags & IDL_V_TEMP) { 
  r = v; 
  dst = src; 
} else { 
  dst.sc = IDL_VarMakeTempFromTemplate(v, v->type, 
                 (IDL_StructDefPre) 0, &r, FALSE); 
} 
  
#define DOCASE(type, field) \ 
case type: for (*dst.field++ = *src.field++; n--;dst.field++)\ 
          *dst.field = *(dst.field - 1) + *src.field++; break
C 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 

#define DOCASE_CMP(type, field) case type: \ 
for (*dst.field++ = *src.field++; n--; \ 
     dst.field++, src.field++) { \ 
  dst.field->r = (dst.field - 1)->r + src.field->r; \ 
  dst.field->i = (dst.field - 1)->i + src.field->i; } \ 
break 
  
   switch (v->type) { 
   DOCASE(IDL_TYP_BYTE, c); 
   DOCASE(IDL_TYP_INT, i); 
   DOCASE(IDL_TYP_LONG, l); 
   DOCASE(IDL_TYP_FLOAT, f); 
   DOCASE(IDL_TYP_DOUBLE, d); 
   DOCASE_CMP(IDL_TYP_COMPLEX, cmp); 
   DOCASE_CMP(IDL_TYP_DCOMPLEX, dcmp); 
   DOCASE(IDL_TYP_UINT, ui); 
   DOCASE(IDL_TYP_ULONG, ul); 
   DOCASE(IDL_TYP_LONG64, l64); 
   DOCASE(IDL_TYP_ULONG64, ul64); 
   default: IDL_Message(IDL_M_NAMED_GENERIC, IDL_MSG_LONGJMP, 
                        "unexpected type"); 
   } 
#undef DOCASE 
#undef DOCASE_CMP 
  
return r; 
}

17

f_src and f_dst are no longer pointers to float. They are now the IDL_ALLPTR type, which can point to data of any IDL type. To reflect this change in scope, the leading f_ prefix has been dropped.

22-23

Strings are the only input type that now require conversion. The other types can either support the computation, or are not convertable to a type that can.

36-38

The code for the running sum computation is logically the same for all non-complex data types, differing only in the IDL_ALLPTR field that is used for each type. Using a macro for this means that the expression is only typed in once, and the C compiler automatically fills in the different parts for each data type. This is less error prone than entering the expression manually for each type, and leads to more readable code. This is one of the rare cases where a macro makes things more reliable and readable.

39-44

A macro for the 2 complex types.

46-60

A switch statement that uses the macros defined above to perform the running sum on all possible types. Note the default case, which traps attempts to compute a running sum on structures.

61-62

Don't allow the macros used in the above switch statement to remain defined beyond the scope of this function.