Quick Navigation Bar
basic c :: functions, preprocessor :: input/output and file i/o
[ toc | forums ]

Note: If the document URL does not begin with http://randu.org/tutorials/c/ then you are viewing a copy. Please direct your browser to the correct location for the most recent version.

Functions and the C Preprocessor

Now that we have a understanding of the very basics of C, it is time now to turn our focus over to making our programs not only run correctly but more efficiently and are more understandable.

Functions :: The Basics

Why should we make functions in our programs when we can just do it all under main? Weiss (pg. 77) has a very good analogy that I'll borrow :) Think for a minute about high-end stereo systems. These stereo systems do not come in an all-in-one package, but rather come in separate components: pre-amplifier, amplifier, equalizer, receiver, cd player, tape deck, and speakers. The same concept applies to programming. Your programs become modularized and much more readable if they are broken down into components.
This type of programming is known as top-down programming, because we first analyze what needs to be broken down into components. Functions allow us to create top-down modular programs.
Each function consists of a name, a return type, and a possible parameter list. This abstract definition of a function is known as it's interface. Here are some sample function interfaces:
```
  char *strdup(char *s)
  int add_two_ints(int x, int y)
  void useless(void)
```
The first function header takes in a pointer to a string and outputs a char pointer. The second header takes in two integers and returns an int. The last header doesn't return anything nor take in parameters.
Some programmers like to separate returns from their function names to facilitate easier readability and searchability. This is just a matter of taste. For example:
```
  int
  add_two_ints(int x, int y)
```
A function can return a single value to its caller in a statement using the keyword return. The return value must be the same type as the return type specified in the function's interface.

Functions :: Prototypes

In the introduction, we touched on function prototypes. To recap, what are function prototypes? Function prototypes are abstract function interfaces. These function declarations have no bodies; they just have their interfaces.
Function prototypes are usually declared at the top of a C source file, or in a separate header file (see Appendix: Creating Libraries).
For example, if you wanted to grab command line parameters for your program, you would most likely use the function getopt. But since this function is not part of ANSI C, you must declare the function prototype, or you will get implicit declaration warnings when compiling with our flags. So you can simply prototype getopt(3) from the man pages:
```
  /* This section of our program is for Function Prototypes */
  int getopt(int argc, char * const argv[], const char *optstring);
  extern char *optarg;
  extern int optind, opterr, optopt;
```
So if we declared this function prototype in our program, we would be telling the compiler explicitly what getopt returns and it's parameter list. What are those extern variables? Recall that extern creates a reference to variables across files, or in other words, it creates file global scope for those variables in that particular C source file. That way we can access these variables that getopt modifies directly. More on getopt on the next section about Input/Output.

Functions :: Functions as Parameters

This is a little more advanced section on functions, but is very useful. Take this for example:
```
  int applyeqn(int F(int), int max, int min) {
    int itmp;
    
    itmp = F(int) + min;
    itmp = itmp - max;
    return itmp;
  }
```
What does this function do if we call it with applyeqn(square(x), y, z);? What happens is that the int F(int) is a reference to the function that is passed in as a parameter. Thus inside applyeqn where there is a call to F, it actually is a call to square! This is very useful if we have one set function, but wish to vary the input according to a particular function. So if we had a different function called cube we could change how we call applyeqn by calling the function by applyeqn(cube(x), y, z);.

Functions :: The Problem

So now you must be thinking... Wow! Functions are great! I can do anything with functions! WRONG. There are four major ways that parameters are passed into functions. The two that we should be concerned with are Pass by Value and Pass by Reference. In C, all parameters are passed by value.
So you're saying so what? It makes a big difference. In simplistic terms, functions in C create copies of the passed in variables. These variables remain on the stack for the lifetime of the function and then are discarded, so they do not affect the inputs! This is important. Let's repeat it again. Passed in arguments will remain unchanged. Let's use this swapping function as an example:
```
  void swap(int x, int y) {
    int tmp = 0;

    tmp = x;
    x = y;
    y = tmp;
  }
```
If you were to simply pass in parameters to this swapping function that swaps two integers, this would fail horribly. You'll just get the same values back.
But thankfully, you can circumvent this pass by value limitation in C by simulating pass by reference. Pass by reference changes the values that are passed in when the function exits. This isn't how C works technically but can be thought of in the same fashion. So how do you avoid pass by value side effects? By using pointers and in some cases using macros. We will discuss pointers in detail later.

The C Preprocessor :: Overview

The C Preprocessor is not part of the compiler, but is a separate step in the compilation process. In simplistic terms, a C Preprocessor is just a text substitution tool. We'll refer to the C Preprocessor as the CPP.
All preprocessor lines begin with #. This listing is from Weiss pg. 104. The unconditional directives are:
- #include - Inserts a particular header from another file
- #define - Defines a preprocessor macro
- #undef - Undefines a preprocessor macro
The conditional directives are:
- #ifdef - If this macro is defined
- #ifndef - If this macro is not defined
- #if - Test if a compile time condition is true
- #else - The alternative for #if
- #elif - #else an #if in one statement
- #endif - End preprocessor conditional
Other directives include:
- # - Stringization, replaces a macro parameter with a string constant
- ## - Token merge, creates a single token from two adjacent ones
Some examples of the above:
```
  #define MAX_ARRAY_LENGTH 20
```
Tells the CPP to replace instances of MAX_ARRAY_LENGTH with 20. Use #define for constants to increase readability. Notice the absence of the ;.
```
  #include <stdio.h>
  #include "mystring.h"
```
Tells the CPP to get stdio.h from System Libraries and add the text to this file. The next line tells CPP to get mystring.h from the local directory and add the text to the file. This is a difference you must take note of.
```
  #undef MEANING_OF_LIFE
  #define MEANING_OF_LIFE 42
```
Tells the CPP to undefine MEANING_OF_LIFE and define it for 42.
```
  #ifndef IROCK
  #define IROCK "You wish!"
  #endif
```
Tells the CPP to define IROCK only if IROCK isn't defined already.
```
  #ifdef DEBUG
    /* Your debugging statements here */
  #endif
```
Tells the CPP to do the following statements if DEBUG is defined. This is useful if you pass the -DDEBUG flag to gcc. This will define DEBUG, so you can turn debugging on and off on the fly!

The C Preprocessor :: Parameterized Macros

One of the powerful functions of the CPP is the ability to simulate functions using parameterized macros. For example, we might have some code to square a number:
```
  int square(int x) {
    return x * x;
  }
```
We can instead rewrite this using a macro:
```
  #define square(x) ((x) * (x))
```
A few things you should notice. First square(x) The left parentheses must "cuddle" with the macro identifier. The next thing that should catch your eye are the parenthesis surrounding the x's. These are necessary... what if we used this macro as square(1 + 1)? Imagine if the macro didn't have those parentheses? It would become ( 1 + 1 * 1 + 1 ). Instead of our desired result of 4, we would get 3. Thus the added parentheses will make the expression ( (1 + 1) * (1 + 1) ). This is a fundamental difference between macros and functions. You don't have to worry about this with functions, but you must consider this when using macros.
Remeber that pass by value vs. pass by reference issue earlier? I said that you could go around this by using a macro. Here is swap in action when using a macro:
```
  #define swap(x, y) { int tmp = x; x = y; y = tmp }
```
Now we have swapping code that works. Why does this work? It's because the CPP just simply replaces text. Wherever swap is called, the CPP will replace the macro call with the defined text. We'll go into how we can do this with pointers later.

Functions and C Preprocessor Review

Functions allow for modular programming. You must remember that all parameters passed into function in C are passed by value!
The C Preprocessor allows for macro definitions and other pre-compilation directives. It is just a text substitution tool before the actual compilation begins.