NumTool-C

NumTool-C is a modular, command-line number-theory calculator written in C. It reads a batch of commands from an input file, evaluates each one using a small library of classic number-theory algorithms, and writes the results to an output file in a clean, predictable format.

This project was developed as a term project for the Programming II course.

---

✨ Features

NumTool-C supports the following commands, each mapped to a well-known number-theory algorithm:

Command	Syntax	Description
GCD	GCD a b	Greatest Common Divisor (Euclidean Algorithm)
POW	POW base exp mod	Modular exponentiation (Binary Exponentiation)
PRIME	PRIME n	Primality test (O(√n) with 6k ± 1 optimization)
INV	INV a m	Modular multiplicative inverse (Extended Euclidean Algorithm)
PHI	PHI n	Euler's Totient function
CHECK	CHECK a m	Verifies that a's modular inverse under m is correct

Multiple commands can be placed on the same line, separated by ;. Lines starting with # are treated as comments and ignored.

Example input (input.txt):

# --- BASIC TESTS ---
GCD 48 18; POW 2 10 1000
PRIME 29
INV 3 11; PHI 36

Example output:

GCD 48 18 -> 6
POW 2 10 1000 -> 24
PRIME 29 -> YES
INV 3 11 -> 4
PHI 36 -> 12

Invalid input (missing/negative arguments, non-invertible values, etc.) is reported directly in the output file using descriptive error tokens such as ERROR_INVALID_INPUT and ERROR_NO_INVERSE.

---

🧩 Project Architecture

The project follows a clean, modular design separating I/O, parsing, and mathematical logic:

NumTool-C/
├── main.c            # Entry point: orchestrates parsing, dispatch, and output
├── parser.c / .h      # Reads and tokenizes the input file into CommandRecord entries
├── math_utils.c / .h  # Number-theory algorithms (GCD, modular inverse, power_mod, etc.)
├── Makefile           # Build automation
├── input.txt          # Sample input file for testing
└── .gitignore         # Excludes build artifacts and IDE files from version control

Module Responsibilities

• parser module — Reads the input file line by line, splits multi-command lines on ;, trims whitespace, and converts each command into a dynamically allocated CommandRecord struct (command name, up to 4 numeric arguments, result buffer, and error flag). The internal array grows dynamically via realloc as more records are read.

• math_utils module — Implements the underlying algorithms:

  • gcd() — Euclidean algorithm, O(log(min(a, b)))
  • mod_inverse() — Extended Euclidean algorithm
  • power_mod() — Binary (fast) exponentiation, O(log exp), with overflow-safe modular reduction
  • is_prime() — Trial division optimized with the 6k ± 1 rule, O(√n)
  • euler_totient() — Prime-factorization-based computation of Euler's φ function

• main module — Validates command-line arguments, invokes parse_file(), dispatches each parsed record to the appropriate math_utils function based on its command name, and writes formatted results to the output file.

---

🛠️ Building the Project

The project is built with the included Makefile, which uses gcc by default.

# Build the numtool executable
make

# Remove all build artifacts (*.o and the numtool binary)
make clean

The Makefile compiles each .c file into an object file (-c) and then links main.o, parser.o, and math_utils.o into the final numtool executable, using -Wall -Wextra for stricter warnings and -O2 for optimized performance.

---

▶️ Usage

./numtool <input_file> <output_file>

Example:

./numtool input.txt output.txt

If the argument count is incorrect, or the input file cannot be opened, the program prints an explanatory message and exits with a non-zero status code.

---

👥 Authors

• ALİ TUTKAÇ - alitutkac
• MAHAMMAD ISMAYILZADA - ismayilzada-m

---

📄 License

This project was developed for academic purposes as part of the Programming II term project.