<WRAP centeralign round box>
<WRAP><color red><fs 200%>Corning Community College</fs></color></WRAP>
<WRAP><fs 150%>CSCS1730 UNIX/Linux Fundamentals</fs></WRAP>
</WRAP>

======Project: COMPUTATION - CALCULATING N-ARY VALUES (cnv0)======

=====Objective=====
To create a script that can calculate and determine the number of factor pairs of a given number, starting with values composed of exactly 2 sets of factor pairs.

=====Background=====
In mathematics, you have likely encountered the notion of "prime" numbers, those values which are divisible only by 1 and the number itself.

Expanding our view on the situation, when considering factors of a number, we have the presence of a "factor pair"; ie a pair of two values that are evenly divisible into that number.

For 17, a prime number, we have just ONE factor pair: 1 and 17:

  * 17 % 1 == 0
  * 17 % 17 == 0

All other values (2-16) when we divide them into 17 results in a non-zero value for the remainder.

In this way, prime, or primary, numbers, have exactly ONE factor pair. To further simplify matters, we can call it an N-ary(1) or nary(1) value. Where the number indicates the number of factor pairs.

A secondary, or nary(2) number, on the other hand, has exactly TWO sets of factor pairs.

Take the number 6, for instance:

  * factor pair of 1 and 6
  * factor pair of 2 and 3

Where 17 was a prime or "primary" number, 6 is a "secondary" number.

====Determining factor pairs====
We are going to be exploring a basic, brute force, method of determining factors for a number, and that is the "trial by division" method.

Here, we successively divide a number by potential factors, to see if the factor evenly divides into the number. For convenience, we will assume the 1 and number factor pair, because EVERY number is evenly divisible by 1 and itself.

So, the number 5:

  * 5 % 2 == 1
  * 5 % 3 == 2
  * 5 % 4 == 1

No other evenly divisible factors were found in the range 2-(N-1), therefore we are only left with the factor pair of 1 and N, making 5 an nary(1) value.

The number 14:

  * 14 % 2 == 0   another factor!
  * 14 % 3 == 2
  * 14 % 4 == 2
  * 14 % 5 == 4
  * 14 % 6 == 2
  * 14 % 7 == 0   another factor!
  * 14 % 8 == 6
  * 14 % 9 == 5
  * 14 % 10 == 4
  * 14 % 11 == 3
  * 14 % 12 == 2
  * 14 % 13 == 1

Because factor pairs ALWAYS come in a set of 2, we have the factor pairs of 1 and 14, along with 2 and 7.

How about 12:

  * 12 % 2 == 0
  * 12 % 3 == 0
  * 12 % 4 == 0
  * 12 % 5 == 2
  * 12 % 6 == 0
  * 12 % 7 == 5
  * 12 % 8 == 4
  * 12 % 9 == 3
  * 12 % 10 == 2
  * 12 % 11 == 1

There are 4 additional factors discovered here, giving us a total of 6 factors, or three factor pairs:

  * 1, 12
  * 2, 6
  * 3, 4

Notice also how the factors are nested: 1 and 12 are the outermost, 2 and 6 are encapsulated within that, and inside there, 3 and 4.

Because there are 3 factor pairs, 12 would be considered an nary(3) value (or a tertiary number).

=====grabit=====
There is a grabit for this project, which will provide you with some files pertinent for performing this project.

Run '**grabit**' on lab46 in the appropriate manner to obtain the files.

=====Loops=====
A loop is basically instructing the computer to repeat a section, or block, or logic a given amount of times (it can be based on a fixed value-- repeat this 4 times, or be based on a conditional value-- keep repeating as long as (or while) this value is not 4).

Loops enable us to simplify our logic-- allowing us to write a one-size-fits all algorithm (provided the algorithm itself can appropriately scale!), where the computer merely repeats the instructions we gave. We only have to write them once, but the computer can do that task any number of times.

Loops can be initially difficult to comprehend because unlike other programmatic actions, they are not single-state in nature-- loops are multi-state. What this means is that in order to correctly "see" or visualize a loop, you must analyze what is going on with EACH iteration or cycle, watching the values/algorithm/process slowly march from its initial state to its resultant state. Think of it as climbing a set of stairs... yes, we can describe that action succinctly as "climbing a set of stairs", but there are multiple "steps" (heh, heh) involved: we place our foot, adjust our balance-- left foot, right foot, from one step, to the next, to the next, allowing us to progress from the bottom step to the top step... that process of scaling a stairway is the same as iterating through a loop-- but what is important as we implement is what needs to happen each step along the way.

With that said, it is important to be able to focus on the process of the individual steps being taken. What is involved in taking a step? What constitutes a basic unit of stairway traversal? If that unit can be easily repeated for the next and the next (and in fact, the rest of the) steps, we've described the core process of the loop, or what will be iterated a given number of times.

In BASH, we will generally focus on the following three types of loops:

  * numeric **for** loop (automatic counter loop, stepping loop; top-driven) - when we know exactly how many times we wish something to run; we know where we want to start, where we want to end, and exactly how to progress from start to end (step value)
  * **while** loop (top-driven conditional loop) - when we want to repeat a process, but the exact number of iterations is either not known, not important, not known, or variable in nature. While loops can run 0 or more times.
  * list-based **for** loop (top-driven conditional loop) - sometimes this is referred to as a "for each" loop: it is provided a set of values , and it will iterate through each one, one at a time.

====numeric for() loops====
A numeric **for** loop is the most syntactically unique of the loops, so care must be taken to use the proper syntax.

With any loop, we need (at least one) looping variable, which the loop will use to analyze whether or not we've met our looping destination, or to perform another iteration.

A numeric for loop typically also has a defined starting point, a "keep-looping-while" condition, and a stepping equation.

Here's a sample numeric for loop, in BASH, which will display the squares of each number, starting at 0, and stepping one at a time, for 8 total iterations:

<code bash>
for ((index=0; index<8; index++)); do
    printf "loop #%d ... %d\n" "$((${index}+1))" "$((${index}*${index}))"
done
</code>

The output of this code, with the help of our loop should be:

<cli>
loop #1 ... 0
loop #2 ... 1
loop #3 ... 4
loop #4 ... 9
loop #5 ... 16
loop #6 ... 25
loop #7 ... 36
loop #8 ... 49
</cli>

Note how we can use our looping variable (**index**) within mathematical expressions to drive a process along... loops can be of enormous help in this way.

And again, we shouldn't look at this as one step-- we need to see there are 8 discrete, distinct steps happening here (when index is 0, when index is 1, when index is 2, ... up until (and including) when index is 7).

The loop exits once **index** reaches a value of 8, because our loop determinant condition states as long as **index** is **less than** **8**, continue to loop. Once **index** becomes **8**, our looping condition has been satisfied, and the loop will no longer iterate.

The stepping (that third) field is a mathematical expression indicating how we wish for **index** to progress from its starting state (of being equal to 0) to satisfying the loop's iterating condition (no longer being less than 8).

**index++** is a shortcut we can use in C; the longhand (and likely more familiar) equivalent is: **index=index+1**

====while loops====
A **while** loop isn't as specific about starting and stepping values, really only caring about what condition needs to be met in order to exit the loop (keep looping while this condition is true).

In actuality, anything we use a for loop for can be expressed as a while loop-- we merely have to ensure we provide the necessary loop variables and progressions within the loop.

That same loop above, expressed as a while loop, could look like:

<code bash>
index=0
while [ "${index}" -lt 8 ]; do
    printf "loop #%d ... %d\n" "$((${index}+1))" "$((${index}*${index}))"
    let index=index+1
done
</code>

The output of this code should be identical, even though we used a different loop to accomplish the task (try them both out and confirm!)

**while()** loops, like numeric **for()** loops, will run 0 or more times; if the conditions enabling the loop to occur are not initially met, they will not run... if met, they will continue to iterate until their looping conditions are met.

It is possible to introduce a certain kind of **logical error** into your programs using loops-- what is known as an "infinite loop"; this is basically where you erroneously provide incorrect conditions to the particular loop used, allowing it to start running, but never arriving at its conclusion, thereby iterating forever.

Another common **logical error** that loops will allow us to encounter will be the "off by one" error-- where the conditions we pose to the loop are incorrect, and the loop runs one magnitude more or less than we had intended. Again, proper debugging of our code will resolve this situation.

====list-based for loops====
The third commonly utilized looping structure in BASH, the list-based for loop (aka "foreach" loop) is based more on providing it a list of tokens (commonly a string, or the expanded output of some command containing interpretable tokens), which get iterated through one at a time.

I encourage you to intentionally try your hand at taking your completed programs and implementing other versions that utilize the other types of loops you haven't utilized. This way, you can get more familiar with how to structure your solutions and express them.

So, expressing that same logic in the form of a list-based for loop:

<code bash>
for index in $(seq 0 7); do
    printf "loop #%d ... %d\n" "$((${index}+1))" "$((${index}*${index}))"
done
</code>

In this case, the command-expanded output of the call to the **seq**(**1**) command is what the loop iterates upon.

=====Script=====
It is your task to write a script that, upon accepting various pieces of input from the user, computes the number of factor pairs of a given number, displaying its eligibility as a secondary number.

=====Specifications=====
Your program should:

  * have valid, descriptive variable names of length //no shorter than// 4 symbols
  * have consistent, well-defined indentation (no less than 4 spaces per level of indentation)
    * all code within the same scope aligned to its indentation level
  * have proximal comments explaining your rationale (the why and how), throughout your code
  * to STDERR, prompt for the number
  * immediately after the input, check to make sure the input number is a positive number greater than or equal to 2; if in violation, display an error (to STDERR) and exit with a non-zero value.
  * proceed to evaluate the input number, determining whether or not it is a secondary (nary(2)) number.
    * if it is, display to STDOUT that it is a secondary number (see execution section below for message)
    * if it is not, display to STDOUT that it is not a secondary number (again, see execution section below)
  * using a single return statement at the conclusion of the code, return a 0 indicating successful operation

=====Execution=====

====Secondary number output====
<cli>
yourpi:~/src/SEMESTER/DESIG/cnv0$ ./cnv0.sh
Enter a number: 6
6 is a secondary number
yourpi:~/src/SEMESTER/DESIG/cnv0$ 
</cli>

====Non-secondary number output====
<cli>
yourpi:~/src/SEMESTER/DESIG/cnv0$ ./cnv0.sh
Enter a number: 7
7 is NOT a secondary number
</cli>

====Additional outputs====
<cli>
yourpi:~/src/SEMESTER/DESIG/cnv0$ ./cnv0.sh
Enter a number: 8
8 is a secondary number
yourpi:~/src/SEMESTER/DESIG/cnv0$ ./cnv0.sh
Enter a number: 16
16 is NOT a secondary number
yourpi:~/src/SEMESTER/DESIG/cnv0$ ./cnv0.sh
Enter a number: 21
21 is a secondary number
yourpi:~/src/SEMESTER/DESIG/cnv0$ 
</cli>

The execution of the program is short and simple- obtain the input, do the processing, produce the output, and then terminate.

=====Process=====
In general, you will be looking to do something like the following:

<code>
DISPLAY PROMPT
READ NUMBER

SHOULD NUMBER BE LOWER THAN TWO:
    DISPLAY AN ERROR
    EXIT WITH A NON-ZERO STATUS

SO LONG AS FACTOR IS LESS THAN NUMBER:
    SHOULD THE FACTOR BE A LEGITIMATE FACTOR OF NUMBER:
        INCREMENT COUNT OF FACTOR PAIRS
        SHOULD THIS NUMBER HAVE A SQUARE FACTOR:
            INCREMENT COUNT OF FACTOR PAIRS

SHOULD THE NUMBER OF FACTOR PAIRS MATCH WHAT WE ARE LOOKING FOR:
    DISPLAY THAT NUMBER BEING PROCESSED IS OF THE NEEDED TYPE
OTHERWISE:
    DISPLAY THAT THE NUMBER BEING PROCESSED IS NOT THE NEEDED TYPE
</code>

=====Reference=====
Copied as part of the grabit, inside your **cnv0/** subdirectory, will be a copy of my implementation (in executable form, by the name **ref_cnv0**), which abides by the project specifications. Please compare its output against that of your implementation. You can invoke the reference implementation by running the following:

<cli>
yourpi:~/src/SEMESTER/DESIG/cnv0$ make check
Enter a number: 6
6 is a secondary number
yourpi:~/src/SEMESTER/DESIG/cnv0$ 
</cli>

=====Verification=====
In addition, I have also placed a **cnv0verify** script in that same subdirectory, which will test your program against a range of values, to determine overall correctness. You can run the verify script using the Makefile, as follows:

<cli>
yourpi:~/src/SEMESTER/DESIG/cnv0$ make verify
[  1] you have: err, should be: err    [  2] you have:  no, should be:  no
[  3] you have:  no, should be:  no    [  4] you have: yes, should be: yes
[  5] you have:  no, should be:  no    [  6] you have: yes, should be: yes
[  7] you have:  no, should be:  no    [  8] you have: yes, should be: yes
[  9] you have: yes, should be: yes    [ 10] you have: yes, should be: yes
[ 11] you have:  no, should be:  no    [ 12] you have:  no, should be:  no
[ 13] you have:  no, should be:  no    [ 14] you have: yes, should be: yes
[ 15] you have: yes, should be: yes    [ 16] you have:  no, should be:  no
[ 17] you have:  no, should be:  no    [ 18] you have:  no, should be:  no
[ 19] you have:  no, should be:  no    [ 20] you have:  no, should be:  no
[ 21] you have: yes, should be: yes    [ 22] you have: yes, should be: yes
[ 23] you have:  no, should be:  no    [ 24] you have:  no, should be:  no
[ 25] you have: yes, should be: yes    [ 26] you have: yes, should be: yes
[ 27] you have: yes, should be: yes    [ 28] you have:  no, should be:  no
[ 29] you have:  no, should be:  no    [ 30] you have:  no, should be:  no
[ 31] you have:  no, should be:  no    [ 32] you have:  no, should be:  no
[ 33] you have: yes, should be: yes    [ 34] you have: yes, should be: yes
[ 35] you have: yes, should be: yes    [ 36] you have:  no, should be:  no
yourpi:~/src/SEMESTER/DESIG/cnv0$ 
</cli>

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

  * Script must execute cleanly (no errors or other noise outside of needed output)
  * Output must be correct, and match the form given in the sample output above.
  * Script must be nicely and consistently indented
  * Script must be well commented
  * Do NOT double space your script. Group like statements together.
  * Output Formatting (including spacing) of script must conform to the provided output (see above).
  * Track/version the script in your lab46 SEMESTER repository
  * Submit a copy of your script to me using the **submit** tool.

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

<cli>
lab46:~/src/SEMESTER/DESIG/cnv0$ make submit
</cli>

And make sure you get no error messages.

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>
52:cnv0:final tally of results (52/52)
*:cnv0:resources obtained via grabit by Sunday before deadline [4/4]
*:cnv0:proper error checking and status reporting performed [6/6]
*:cnv0:correct variable name lengths used [6/6]
*:cnv0:proper output formatting per specifications [6/6]
*:cnv0:proper selection logic applied to perform comparisions [6/6]
*:cnv0:proper iteration logic applied to carry out process [6/6]
*:cnv0:runtime verify tests of submission succeed [6/6]
*:cnv0:no error messages while running script [6/6]
*:cnv0:code is pushed to lab46 SEMESTER repository [6/6]
</code>

Additionally:
  * Solutions not abiding by spirit of project will be subject to a 50% overall deduction
  * Solutions not utilizing descriptive why and how comments will be subject to a 25% overall deduction
  * Solutions not utilizing indentation to promote scope and clarity will be subject to a 25% overall deduction
  * Solutions not organized and easy to read are subject to a 25% overall deduction