Project: COMPUTATION - CALCULATING N-ARY VALUES (cnv1)

Objective

To create a program that can calculate and determine the number of factor pairs (nary value) over a given range of numbers.

Reading

In “The C Book”, please read through Chapter 8.

Review needed concepts in this tutorial and also this one

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 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).

Command-line arguments

To facilitate our activities, we will be making use of command-line arguments in our programs.

Command-line arguments are simply the tokens (space-separated pieces of information) we provide to the computer at the prompt:

lab46:~/src/SEMESTER/DESIG/project$ ./project token1 token2 ... tokenN

The operating system packages up this information and provides it to our program, allowing us to access it.

The first token (“./project”) will be the invocation of our program, allowing our programs to know what they are called.

The second token is the argument that immediately follows (in our case, “token1”); the third is “token2”, and on and on until our very last provided argument (“tokenN” in our conceptual example).

In addition to all the arguments packaged together in an array of strings, we are also provided with a total overall argument count, so we can know how many elements there are in this array of strings.

argument naming conventions

Although you can name them anything, conventionally in many documents these have been named:

argc (or ac): the argument count, a signed integer (int argc)
argv (or av): the array of strings (or an array of an array of char), a double pointer (char **argv)

accepting command-line arguments in your program

To access this command-line information, we provide arguments to our main() function, as follows:

int main (int argc, char **argv)
{

We then have access to those populated variables (when we run a program, we are calling main(), so it should make sense that the arguments we provide to our program are passed as parameters to our main() function, the starting point of our program).

accessing our arguments

The arguments are accessible via the argv array, in the order they were specified:

argv[0]: program invocation (path + program name)
argv[1]: first argument to the program (2nd argument to the command-line)
argv[2]: second argument to the program (3rd overall on the command-line)
…
argv[N]: the last provided argument

N in this case is equivalent to (argc - 1), as is commonly the case with array size and addressing.

Additionally, let's not forget the argc variable, an integer, which contains a count of arguments (argc == argument count). If we provided argv[0] through argv[4], argc would contain a 5 (because array elements 0-4 indicate 5 distinct array elements).

example

For example, if we had the following program:

lab46:~/src/SEMESTER/DESIG/project$ ./project 128 1 2 2048

We'd have:

argv[0]: “./project”
argv[1]: “128” (note, NOT the scalar integer 128, but a string)
argv[2]: “1”
argv[3]: “2”
argv[4]: “2048”

and let's not forget:

argc: 5 (there are 5 things, argv indexes 0, 1, 2, 3, and 4)

Simple argument checks

While there are a number of checks we should perform, one of the first should be a check to see if the minimal number of arguments has been provided:

    if (argc < 3)  // if less than 3 arguments (program_name + argv[1] + argv[2] == 3) have been provided
    {
        fprintf(stderr, "%s: insufficient number of arguments!\n", argv[0]);
        exit(1);
    }

Trying to access a non-existent argument could result in a segmentation fault. ALWAYS check your count to ensure the desired argument exists at the given position.

header files

We don't need any extra header files to use command-line arguments, but we will need an additional header file to use the atoi(3) function, which we'll use to quickly turn the command-line parameter into an integer, if such an operation is needed; and that header file is stdlib.h, so be sure to include it with the others:

#include <stdio.h>
#include <stdlib.h>

In the above example, if argv[1] was “128” and we actually wanted that as an integer (versus the string it is initially available as), we utilize atoi(3) in the following manner:

    int value  = 0;
 
    value      = atoi (argv[1]);

NOTE: you will want to do proper error checking and first ensure that argv[1] even exists (by checking argc). Failure to do so may result in a segmentation fault.

2020/10/15 08:40 · wedge

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, then move them to your development system used in this class.

Compiling

Since there is a provided Makefile in the project grabit, we can use that to compile, either regularly:

yourpi:~/src/cprog/cnv1$ make

Or, with debugging support:

yourpi:~/src/cprog/cnv1$ make debug

Program

It is your task to write a program that, upon accepting various pieces of input from the user, computes the number of factor pairs of a given number or range of numbers, displaying to STDOUT all the numbers in that range that qualify as that N-ary value.

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 and what is going on, throughout your code
from the command-line, obtain the needed parameters for your program (require these arguments to be present, displaying errors to STDERR and exiting if they are not present):
- argv[1]: N-ary value (how many factor pairs are we requiring; 1 for prime, 2 for secondary, 3 for tertiary, etc.); this should be stored and managed as an unsigned char.
- argv[2]: lower-bound (where to start processing, inclusive of the lower bound value); this should be stored in an unsigned short int
- argv[3]: upper-bound (where to stop processing, inclusive of the upper bound value); this should be shored in an unsigned short int
immediately after parameter processing, check to make sure the specified parameters are positive numbers. Any deviations should be displayed as error messages to STDERR:
- N-ary value must be between 1 and 16 (inclusive of 1 and 16)
  - on error display “ERROR: invalid nary value (#)!” and terminate execution sending back a 1 (the # should be the actual number in deviation)
- lower bound must be between 2 and 40000 (inclusive of 2 and 40000)
  - on error display “ERROR: invalid lower bound (#)!” and terminate execution sending back a 2 (the # should be the actual number in deviation)
- upper bound must be between 2 and 65000 (inclusive of 2 and 65000)
  - on error display “ERROR: invalid upper bound (#)!” and terminate execution sending back a 3 (the # should be the actual number in deviation)
  - on situation of lower bound being greater than upper bound, display “ERROR: lower bound (#) is larger than upper bound (#)!”, terminating execution and sending back a 4 (the # should be the actual number in deviation)
proceed to evaluate the appropriate number range, determining whether or not it is an N-ary number of runtime specification
- if it is, display the value to STDOUT in space-separated form (see execution section below for format)
- if it is not, do not display anything related to that value (again, see execution section below)
using a single return statement at the conclusion of the code, return a 0 indicating successful operation
- for all error results, use exit() instead; there should only be exactly ONE return() statement per function

Some additional points of consideration:

Note that the driving variables in your loops need to be at least of type short int, otherwise you may get a warning when you compile it.

Execution

Primary number (nary(1)) output

yourpi:~/src/cprog/cnv1$ ./cnv1 1 8 24
11 13 17 19 23 
yourpi:~/src/cprog/cnv1$

Secondary number (nary(2)) output

yourpi:~/src/cprog/cnv1$ ./cnv1 2 3 12
4 6 8 9 10 
yourpi:~/src/cprog/cnv1$

Tertiary number (nary(3)) output

yourpi:~/src/cprog/cnv1$ ./cnv1 3 11 37
12 16 18 20 28 32 
yourpi:~/src/cprog/cnv1$

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

Reference

In the CPROG public directory, inside the cnv1/ subdirectory, will be a copy of my implementation (in executable form, by the name ref_cnv1), which abides by the project specifications. Please compare its output against that of your implementation. You can run “make check” to have it run your program through a few variations:

yourpi:~/src/cprog/cnv1$ make check
n-ary(1) from 2 to 50: 2 3 5 7 11 13 17 19 23 29 31 37 41 43 47
n-ary(2) from 2 to 50: 4 6 8 9 10 14 15 21 22 25 26 27 33 34 35 38 39 46 49
n-ary(3) from 2 to 50: 12 16 18 20 28 32 44 45 50
n-ary(4) from 2 to 50: 24 30 40 42
n-ary(5) from 2 to 50: 36 48

Verification

In addition, I have also placed a cnv1verify script in that same subdirectory, which will test your program against a range of values, to determine overall correctness. You can run it by doing a “make verify”:

yourpi:~/src/cprog/cnv1$ make verify
ERROR CHECK
=================
invalid nary (0): ERROR: invalid nary value (0)!
     exit status: 1, should be: 1
- - - - - - -
invalid nary (17): ERROR: invalid nary value (17)!
     exit status: 1, should be: 1
- - - - - - -
invalid lower (1): ERROR: invalid lower bound (1)!
     exit status: 2, should be: 2
- - - - - - -
invalid lower (43100): ERROR: invalid lower bound (43100)!
     exit status: 2, should be: 2
- - - - - - -
invalid upper (0): ERROR: invalid upper bound (0)!
     exit status: 3, should be: 3
- - - - - - -
invalid upper (65501): ERROR: invalid upper bound (65501)!
     exit status: 3, should be: 3
- - - - - - -
lower (300) bigger than upper (65): ERROR: lower bound (300) is larger than upper bound (65)!
     exit status: 4, should be: 4
- - - - - - -
Press ENTER to continue verification tests
nary( 1)
========
   have: >23 29 31 <
   need: >23 29 31 <

nary( 2)
========
   have: >21 22 25 26 27 33 34 35 <
   need: >21 22 25 26 27 33 34 35 <

nary( 3)
========
   have: >20 28 32 <
   need: >20 28 32 <

nary( 4)
========
   have: >24 30 <
   need: >24 30 <

nary( 5)
========
   have: >36 <
   need: >36 <

yourpi:~/src/cprog/cnv1$

Submission

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

Code must compile cleanly (no notes, warnings, nor errors)
Output must be correct, and match the form given in the sample output above.
Code must be nicely and consistently indented, to show scope and maximize readability
Code must be well commented (why and how comments)
Do NOT double space your code. Group like statements together.
Output Formatting (including spacing) of program must conform to the provided output (see above).
Track/version the source code in your lab46 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:

lab46:~/src/cprog/cnv1$ make submit

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:

91:cnv1:final tally of results (91/91)
*:cnv1:resources obtained via grabit by Sunday before deadline [13/13]
*:cnv1:proper error checking and status reporting performed [13/13]
*:cnv1:correct variable types and name lengths used [13/13]
*:cnv1:proper output formatting per specifications [13/13]
*:cnv1:runtime tests of submitted program succeed [13/13]
*:cnv1:no negative compiler messages for program [13/13]
*:cnv1:code is pushed to lab46 repository [13/13]

Additionally:

Solutions not abiding by spirit of project will be subject to a 25% overall deduction
Solutions not utilizing descriptive why and how comments will be subject to a 25% overall deduction
Solutions not utilizing consistent, sensible 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

Lab46 Wiki

Table of Contents