<WRAP centeralign round box>
<WRAP><color red><fs 200%>Corning Community College</fs></color></WRAP>
<WRAP><fs 150%>CSCS1320 C/C++ Programming</fs></WRAP>
</WRAP>

~~TOC~~

======Project: FUNCTIONS - FOX, CHICKEN, CORN (fcc0)======

=====Objective=====
To begin the exploration of functions, and their impact on code modularity/design.

=====References=====
I found a decent explanation of functions in this on-line book; you may also consult the function topics in the listed books for the course:

  * Chapter 4 ("Functions") in [[http://publications.gbdirect.co.uk/c_book/chapter4/|The C Book]] for additional information on functions.

=====Background=====
So far in this course you have been introduced to methods of data storage, I/O, selection/decision control, and iteration. You've been implementing all these inside **int main()**, which you've been required to place in every single program.

We're now moving on to this function thing.. and, guess what? As I've pointed out all along: **main()** is a function!

=====What is a function?=====
In a way, functions are like evolved variables - they have a data (return) type, they are given a symbolic name, and they contain information.

Functions are like sub-programs - small subroutines that perform some specific task that is relevant to the larger program (or other functions).

So, instead of storing some numeric value like variables do, functions contain a group of instructions which can give way to a final numeric value (or values).

That group of functions, which performs a task, is given a name. That will allow your function to be called from wherever it is needed, and can be used to prevent the needless duplication of code to do some common task a number of times.

The data type assigned to the function correlates to the //return value// - the data which is returned from a function as a result of its actions.

====Why should I use functions?====
As I've said, the absolute minimal number of functions required in a C program is 1: **main()**

**main()** is a regular ordinary function with one notable difference-- it is the one function the system looks for to start executing your program. Aside from that, it is as real and normal a regular function as any other you create.

Why can't I just put everything in **main()**?

Nothing is preventing you from exclusively using **main()**. However, your program may become unnecessarily long and difficult to debug should there be problems. Functions allow you to modularize your code- so you can break it up into little pieces. Not only can this lead to increased efficiency from less duplicated code, but your code will be significantly more organized.

For this course, I will expect you to use functions from this point on.

====Where do I put functions in my program?====
There are two aspects to functions, which are concepts shared with that of variables:

  * declaration / prototyping
  * definition / initialization

In order to avoid compiler errors, and allow your code to work seamlessly with your functions, ANY functions must be **declared** prior to any other function that makes use of them.

Once the function is declared, the definition could then immediately take place (just as is the case with variables where we can initialize them), or you can defer definition to later.

====When do I use functions?====
Programming is more of an art, so there is no clear-cut answer to this. However, here are a couple of guidelines you should keep in mind as good indications for needing a function:

  * you find yourself duplicating a section of code two or more times.
  * your program solves a problem that can be broken up into independent steps, or operations.
  * the task or subtask you are implementing is longer than you have lines for on your terminal (this one comes with practice).

Some thoughts to consider when implementing functions:

  * a function typically performs a single task (such as taking input from the keyboard, OR processing something, OR displaying output). Don't try to do all of this in a single function, else you may end up defeating the purpose of using a function in the first place. Sometimes you will want to mix things together, but at this stage, the aim is to develop good programming habits and an aesthetic for effective function use.
  * if you have similar, but not exactly identical, tasks to implement, see if your resulting function can't somehow be created to accommodate some number of them.

====How do I implement a funtion?====
A function consists of the following:

  * **__return type__**: this can be any valid data type available to you in C, with the addition of **void**.

  * **__function name__**: the identifier for the function. Just as you've given names to your variables in order to access them, the function name allows you to identify the function and to call it from within your program.

  * **__parameters__**: these are pieces of information that are sent into your function for processing. Parameters are like local copies of variables you send in. And like variables of local scope, they don't exist outside their particular block of code.

  * **__function body__**: the bulk of the function. This is the code you implement that accomplishes a particular task.

====Function vs. Procedure====

Technically, a function returns exactly 1 value (corresponding to the return statement that is placed at the end). A procedure can "return" 2 or more values. I say "return", because you are only allowed the use of one return statement per function body, and it must be at the end of the program flow of that subroutine.

But what if we want to return nothing? Well, even though it is possible with the use of the **void** data type, it is generally not good practice. If you are not returning a meaningful value, you should at least return an exiting value signifying success or failure.

For example:

  * If your function was successful, you should return a 0.
  * If your function was unsuccessful, you should return a non-zero value, such as 1. (You can setup different non-zero values to signify different levels of error within your program).

Ok, so if we're allowed only one return statement, how can we return more than one value? The simple answer is- we cheat. By employing the use of pointers, we can perform what is called passing a parameter by reference or address; instead of making a local copy, we actually obtain direct access to the memory location of that parameter, so when we make modifications, the changes remain even outside the function.

So, by using pointers in our function's parameter list, we can simulate the notion of //procedures//.

====Pass by value / Pass by address====
In many programming text books, you will see reference to "pass by value" and "pass by reference". As it turns out, in C, instead of pass by "reference", we have "pass by address".

===Pass by value===
When we pass by value, a copy of a variable is made, and is entirely independent (aside from the initial value of the data) of the source data.

Any changes made to that variable within the function remain within the function-- no changes are reflected back in the original variable (unless otherwise manipulated).

Passing by value is easy, we just declare variables within the parenthesis as normal:

<code c>
int funcname(int var1, int var2)
{
</code>

In this case, the function **funcname** has 2 parameters, both of type **int**: var1 and var2

So, to **call** our function //funcname//:

<code c>
result = funcname(value1, value2);
</code>

In this case, **value1** gets sent in as the first parameter (and **var1** is declared and set equal to **value1**). Similar case for **value2**/**var2**.

===Pass by address===
When we pass by address, we use pointers to connect the function parameters to the actual memory space of a variable outside the function.

We do this by using the <nowiki>*</nowiki> and <nowiki>&</nowiki> pointer operators.

A sample function declaration:

<code c>
int funcname(int *val1, int *val2)
{
</code>

And then, to call this function, we do as follows:

<code c>
result = funcname(&in1, &in2);
</code>

=====Program=====
Using functions, we are going to implement the classic "Fox, Chicken, Corn" game.

====Rules====
The premise of this game involves a farmer with the above-mentioned items that needs to transport them across a stream in a boat.

The boat, unfortunately, is large enough only for the farmer and one item.

There exists the following relationship with the items:

  * The fox, left alone with the chicken, will eat the chicken.
  * The chicken, left alone with the corn, will eat the corn.

So one needs to craft a careful means of transporting all these items without losing any of them.

====Programming Considerations====

  * Your program should display the current scene (using textual characters)
    * visualize the location of the farmer, fox, chicken, corn, river, and boat
  * Do not worry about "clearing the screen"; just redraw the scene after each round
  * At the start of the game, prompt the user for a display of the game rules and instructions
  * At the conclusion of the game:
    * display the total number of turns taken before the game reached its end (successful or otherwise) state
    * prompt the user if they would like to play again
  * Create, populate, and use the following functions:
    * **intro();** - a function to display the instructions for the game
    * **display();** - a function to display the current playing field
    * **chkmove();** - a function called after each turn to determine if the game is over (user chooses poorly), or if the game is still in session
  * There are to be **NO** global variables used in your program. Pass any needed variables by value or address between functions
  * Of your variables and functions, you are to pass **at least** one variable by address and manipulate it within the called function (so the changed value is reflected outside the called function as well).
  * You are also to pass **at least** one variable by value and utilize it with the called function.
  * Implement your code in a single .c file- **fcc0.c**

=====Programming Assumptions=====
A couple things to keep in mind:

  * be creative in your design and implementation of this game.
  * consistently indent your code so that it is readable!
  * document your code so I know you know what you're doing
    * and, weeks from now, so will you.
  * Polish your output so it appears consistent to the end user

=====Contemplations=====
Perhaps things that could be incorporated into your weekly journal entry...

  * Provide a code snippet that will successfully call the **powf(3)** function and display the result of a sample operation (this is a real function, part of the math library).
  * A **result()** function returns an **int** but you want to store it in a **float**, show me how you'd do this.
  * Show me the code that calls the following function: **int sample(int *, int);**

=====Review of Compiling/Executing=====
Just to review the compilation/execution process for working with your source code, if we had a file, **hello.c**, that we wished to compile to a binary called **hello**, we'd first want to compile the code, as follows:

<cli>
lab46:~/src/cprog$ gcc -Wall --std=c99 -o hello hello.c
lab46:~/src/cprog$ 
</cli>

Assuming there are no syntax errors or warnings, and everything compiled correctly, you should just get your prompt back. In the event of problems, the compiler will be sure to tell you about them.

Conceptually, the arrangement is as follows:

<code>
gcc -Wall --std=c99 -o BINARY_FILE SOURCE_FILE
</code>

The BINARY_FILE comes **immediately after** the **-o**, **NOT** the SOURCE_FILE (it must never **immediately** follow a **-o**). It can precede, and such is perfectly valid (especially if you feel that way more intuitive).

The **-Wall** (treat all warnings as errors, increase general verbosity about warnings) and **--std=c99** (switch compiler to use the **C99** standard of the C language) are options given to the compiler.

To execute your binary, we need to specify a path to it, so we use **./**, which basically references the current directory:

<cli>
lab46:~/src/cprog$ ./hello
Hello, World!
lab46:~/src/cprog$ 
</cli>

=====Submission=====
To successfully complete this project, the following criteria must be met:

  * Code must compile cleanly (no warnings or errors)
    * Use the **-Wall** and **--std=c99** flags when compiling.
  * Output must be correct, and resemble the form given in the sample output above.
  * Code must be nicely and consistently indented (you may use the **indent** tool)
  * Code must utilize the algorithm presented above
  * Code must establish and utilize the functions described above
  * Code must be commented (and those comments relevant)
  * Track/version the source code in a repository
  * Submit a copy of your source code to me using the **submit** tool.

To submit this program to me using the **submit** tool, run the following command at your lab46 prompt:

<cli>
$ submit cprog fcc0 fcc0.c
Submitting cprog project "fcc0":
    -> fcc0.c(OK)

SUCCESSFULLY SUBMITTED
</cli>

You should get some sort of confirmation indicating successful submission if all went according to plan. If not, check for typos and or locational mismatches.

What I'll be looking for:

<code>
78:fcc0:final tally of results (78/78)
*:fcc0:project submitted [6/6]
*:fcc0:FCC game adequately implemented [6/6]
*:fcc0:consistent and relevant commenting [6/6]
*:fcc0:consistent indentation [6/6]
*:fcc0:output consistent with project specifications [6/6]
*:fcc0:compiles with no messages generated [6/6]
*:fcc0:correct operation (run 1/4) [6/6]
*:fcc0:correct operation (run 2/4) [6/6]
*:fcc0:correct operation (run 3/4) [6/6]
*:fcc0:correct operation (run 4/4) [6/6]
*:fcc0:intro function works and used [6/6]
*:fcc0:display function works and used [6/6]
*:fcc0:chkmove function works and used [6/6]
</code>