Louis Zirkel III
Salt Lake City, UT

A

I was just out in Utah teaching C++ at Novell and trying out slickrock biking in Moab. This is a slicky-tricky expression. The expression will be evaluated to a value, unfortunately one that is undefined. It may appear that it is definable, since it will probably work the same way on a particular hardware/software combination. There are two reasons why this expression is undefined. The expression contains side effects and the order of evaluation of an expression is not specified. Let's examine these separately.

According to the ANSI standard, a side effect is a change in the state of the execution environment. Modifying an object, accessing a volatile object, modifying a file, or calling a function that does any of these operations are all side effects. A side effect that is the result of the evaluation of an expression will be complete at a sequence point. The end of a full expression and the comma operator are sequence points. In your example:

 int X = 5;
 X = X++ + ++X;

 int X = 5;
 X = X++;

 int X = 5;
 X++ + ++X;

If the left-hand side is computed first, the pre-increment will occur, so you will get 6 + 6, or 12. For those who really want to consider another possibility, the pre-increment might only happen to a temporary register and not to X's memory location. This would make this computation 5 + 6, or 11. I'm sure you can come up with some more possibilities, especially with the assignment operator thrown in.

I use an example similar to this in my C classes. As an indication of the uncertainty, I have the students decide on what is the "right" value for the expression. Then they run a program to determine the computer's value. I have not recorded all the results, but about 50 percent of the time the students are wrong. And the value is not the same on all computers.

The ANSI standard states that between the previous and next sequence point, an object shall have its stored value modified at most once by the evaluation of an operand. The prior value shall be accessed only to determine the value to be stored. If this rule is violated, the result is undefined. This rule sort of combines both the side effect and the order of evaluation rules.

The example you gave is a fairly obvious violation of these rules. Subtler errors include statements as:

array[i++] = i;

array[i++] = array[i] + 1;

array[i++] += 1;

I'll mention one other aspect of side effects. If your program handles signals, only the values of objects as of the previous sequence point may be relied upon. For example, there is no telling what the value of X will be if the expression evaluation was interrupted.

A reference work that we have found to be most useful, although seriously dated, is The C Programmers Guide to Serial Communications by Joe Campbell; copyright 1987, published by Howard W. Sams & Company, ISBN #0-672-22584-0.

We have found this book to be an invaluable tool in using serial communications. Although it only lists the commands for Hayes Modems (Models 300, 1200, 1200B, 1200+, 1200B+, 2400, and 2400B), it is still useful. It also gives a very good discussion of basic serial communications concepts, cabling, portability concerns, and UART Programming (8250 and Z80SIO).

So far, even though it's dated, this is still the best book I've found on the subject. We have also discovered that most modem manufacturers are more than willing to send (via fax or mail) a copy of their various "AT" and S-register commands. A call to a hardware distributor will usually land you the names and phone numbers of all of the manufacturers they carry, and then you're usually just a phone call away.

Thanks for an excellent column.

Rob Hedin
Florida

Thanks for your reply. It sounds like there's the potential for a library that handles the differences in modem control. Perhaps each modem manufacturer could provide a "modem driver" that would perform a standard set of commands. A user would not have to read what the command sequence is to do touch-tone dialing. He would simply load the manufacturer's driver with his communication program.

This driver might be a bit lengthier than a standard device driver, but it would help the developer as well as the user. Of course there may always be a few operations that do not make sense to support in the general world. Just as screen designers went past MS-DOS to get to the BIOS or memory for higher speeds, so might a few communication developers go directly to the modem hardware. One of the features that these drivers could support is built in transmit and receive buffering. This could be implemented regardless of whether the hardware actually provided it.

Bill Smith
New York City, NY

I have seen class documentation go both ways. And whichever way it appears for a particular class library, I like it the other way, of course. This relates to the naming conventions that have been discussed in previous columns. How much information do you repeat in a name, or in this case, in the description of a class?

I feel that having a full listing of functions for each class is desirable. A class user should not have to trace up the entire inheritance tree to find out what functions are available for a particular class. The functions do not have to be described in detail, but references back to a single full explanation can be made. If the function name and parameters do not adequately describe its use, then a description of their purposes should be included in the listing.

One gross omission with a user interface package that I have been reviewing is the lack of documentation on the over-all class model. This particular package derives a number of classes from other classes. A nice description of how the classes interrelate, and not just an inheritance diagram, would be valuable in rapid understanding of the overall structure.

On the other hand, the manual for this particular package repeats for every object the same two pages of full definition for some parameter values that are common to almost all the objects. This repetition makes it harder to find those features that are unique to an object.

There is a coincidental aspect of how C++ objects are documented that I find appealing over normal manuals. Rather than alphabetically arranged manuals, I prefer ones which are grouped by functional usage. For example, MKDIR, RMDIR, and CD should be next to one another, so that I do not have to page flip to find the see alsos. I can always use an index to find the page for a particular function whose name I know. But finding the function by purpose tends to be difficult. With C++, functions are grouped by class. So related functions tend to lie in proximity with each other. Since you are writing documentation, I will make a strong suggestion. The index is the most important part of the book. There are several well-known programs that have probably the worst indices that I have ever run across. They are simply pagination tables for commands and text headers. Look in a database program index and try to find a term that would lead to something simple like clearing the screen. Try Screen, clearing or Clearing the screen. Nothing. Okay, how about Display, clearing or Clearing anything. Still nothing. Erasing maybe. No. You get my point. An index should include additional keys in order to make it easy to find desired information.

data_type **variable;

There are at least two basic uses for double pointers. The first is to receive the address of a variable which is a pointer. The second is as a handle for objects that are allocated. Some people use a double pointer in a fashion similar to using pointers for array parameters. For example, you have seen:

   int integer_array[10];
   function(integer_array);

   function(int *integer_array)
     {
     ...
     }

   function(int integer_array[])
     {
     ...
     }

If the array that is being passed is an array of pointers as

   int *integer_array[10];
   function(integer_array);

   function(int **integer_array)
     {
     ...
     }

   function (int *integer_array[])
     {
     ...
     }

I would use a double pointer unquestionably if the operation of the function required changing the value of a parameter which was an address. The simplest example is one that might be used to parse an input string one token at a time. For example, you might have variables that look like:

   char buffer[] = "ABC,DEF.GHI";
   char * pointer_to_char;
   char * starting_char;
   char delimiters[] = ",.\t";

   pointer_to_char = buffer;
   starting_char = buffer;
   do
     {
     index = parse(&pointer_to_char, delimiters);
     switch(index)
       {
     case ',':
       /*  Do appropriate actions */
     
     }
   starting_char = pointer_to_char;
   } while (index >= 0);

   int parse(char ** pointer_to_pointer_to_char,
     char delimiters[])
     /* Return index of delimiter
       or < 0 if end of string       */
     /* Alter the pointer whose address is passed to
       point to the next character after the
       delimiter (or to the terminating NUL) */
     {
     /* Contents */
     }

Suppose the operating system returns to you a double pointer to memory, usually called a handle. What you receive is the address of a variable that points to the actual memory location. In order to make a reference to actual memory, you use two indirection operators on that handle.

Now the operating system can change the location of the actual memory that is allocated. Of course it cannot change the address at which it is storing that location (the value which it returned to you as the handle). The time at which the operating system can move the allocated memory is system-dependent. It will not (or should not) do it while you are referring to that memory. You may have to lock your handle while you use it in order to avoid referencing moving memory.

The coding technique for using a handle might look like the following. This assumes the name for the system routine is handle_allocate:

typedef void **HANDLE;
  int *int_pointer;
 
  HANDLE a_handle = handle_allocate(memory_size);
  int_pointer = *a_handle;
  // Use int_pointer as normal pointer