Explanation of New Concepts

Here we explain some new features in the code `nr.cc`.

 ``` #define N 100 // Maximum number of iterations ```

This is a common way to define a constant that could be changed some day. Notice that the maximum number of iterations `N` is used twice in the code. It is good practice to refer to it as a symbol and define the value of the symbol only once. Then if we change its value, we need to make only one change and don't have to search the code. The `#define` statements should come near the top of the code where they are easy to find. The symbol `N` is technically called a ``macro''. The compiler preprocessor automatically replaces every instance of the macro with its value before turning the code over to the compiler. So `N` is not a variable, has no specific type, and is not allocated storage.

 ``` for(i = 0; i < N; i = i + 1){ ... } ```

This is a `for` loop. It specifies that the statements between the braces should be executed repeatedly as long as `i < N`, starting with `i = 0` and increasing `i` by one when the last statement in the braces is reached.

We use a `for` loop here to impose a maximum number of Newton Raphson iterations, and prevent the code from running on endlessly.

The generic pattern is

```  for(starting-statement; logical-expression; incrementing-statement){
statement block
}
```
Note that the logical expression is tested before entering the block of statements. So in the above example, if it happened that `N == 0` the condition `i < 0` would be false and the statement block would be skipped altogether.

Because incrementing a counter by one unit is done so often, C++ has a shorthand, `i++` in place of `i = i + 1`; you will often see a `for` loop written this way:

```  for(i = 0; i < N; i++){
...
}
```
It is also written `++i`. In this context it means the same thing.

We could accomplish the same thing with a `while` loop. Here is the logically equivalent pattern;

```  i = 0;
while(i < N){
...
i++;
}
```
Notice that here we have to take care to place the initialization and incrementing statements in the correct place. And it takes three statements to do the job of one `for` statement. For those reasons the `for` loop is preferable here.

The generic form is

```  while(logical-expression){
statement-block
}
```
The while loop repeats the statements inside the statement block as long as the logical expression is true. It is up to the programmer to assure that there is an escape from the loop, so it doesn't run on indefinitely - another reason to be cautious about using a `while` loop where a `for` loop will do.

The `do ... while` structure is much less used. The general syntax is

```  do{
statement-block;
} while(logical-expression);
```
This loop structure is very similar to the `while` loop structure, except that the logical expression is checked only after executing the statement block at least once. (With the `while` loop the statement block is not executed at all if the logical expression is false.) Then in both cases the block is executed repeatedly as long as the logical expression remains true.

 ``` if(abs(p-pnew) < tol){ ... } ```

This test is called the stopping condition for the method. We stop when the absolute value of the change in the estimated root is less than the specified tolerance. We want the absolute value of the change, since it could be positive or negative.

 ``` return 0; ```

This statement forces an exit from the main program. The value 0 is the exit code. It is common practice to use an exit code of 0 for a normal completion and a nonzero code for an abnormal condition. Notice that at the bottom of the code we give an exit code of 1 to signal that the method did not converge. You can check the exit code of your program in the shell `tcsh` using the Unix command
```   echo \$status
```
immediately after your program exits. In the `bash` or `sh` shell the command is `echo \$?`.

Another common way to exit the main program is to call the exit function as in

```      exit(0);
```
where the number in parentheses is the desired exit code.

The `break` statement provides another way out of a loop. We could have written

```  for(i = 0; i < N; i = i + 1){
...
if(abs(p-pnew) < tol)break;
}
```
The break statement immediately quits the statement block controlled by a `for`, `while` or `do ... while` loop, and proceeds with the next statement after the closing brace.

The logical problem in this case is that we reach the same point in the code if the process doesn't converge. So we need to check the value of `i` to be sure that didn't happen. For example, we could end it this way:

```  for(i = 0; i < N; i = i + 1){
...
if(abs(p-pnew) < tol)break;
}
if(i >= N){
cerr << "Failed to converge after " << N << " iterations.\n";
return 1;
}
cout << "Root is " << pnew << " to within "
<< tol << "\n";
return 0;
```

For completeness we mention the `continue` statement. It provides another way to skip around in a loop. While `break` skips the rest of the statement block and quits the loop, the `continue` statement skips the rest of the statement block and proceeds with the next iteration. Here is an example of its use in the same code:

```  for(i = 0; i < N; i = i + 1){
...
if(abs(p-pnew) > tol)continue;
cout << "Root is " << pnew << " to within "
<< tol << "\n";
return 0;
}
cerr << "Failed to converge after " << N << " iterations.\n";
return 1;
```
Notice that the inequality is reversed so the loop continues as long as the shift in the root is larger than the tolerance and `i < N`. I find the original coding style clearer, however, since the code handling the special case is set off clearly with braces and indentation. The `continue` statement is more appropriate when the standard nesting of statement blocks is awkward or when continuation is the unlikely alternative, which is not the case here.

 ``` cerr << "Failed to converge after " << N << " iterations.\n"; ```

The `iostream` object `cerr` works just like `cout` but sends the output to the `stderr` device instead of `stdout`. By default the `stderr` device, like the `stdout` device, is the console. The main reason for using it for error messages is that if a user is redirecting standard output to a file or pipe, the error message would still appear on the screen rather than disappearing into the file or pipe and possibly being ignored.