Advanced Trigonometry Calculator Developer Guide

This guide gives a high-level view of the Advanced Trigonometry Calculator (ATC) codebase. It is intentionally factual and cautious; source code remains the authority for exact behavior.

For contribution recipes, checklists and practical "how to add" notes, see docs/en/Developer_Reference.md.

Project Purpose

ATC is a C++ Windows command-line mathematical application. It evaluates text-based expressions and documented commands in a console environment.

The project supports numerical workflows involving arithmetic, trigonometry, complex numbers, matrices, statistics, polynomial tools, equation solving, variables, and configurable precision.

ATC should not be described as having broad symbolic-algebra capabilities that are not documented in the repository.

Source Structure

The main source directory is:

Advanced Trigonometry Calculator/

Important source areas include:

• main.cpp: startup, precision-mode dispatch, top-level console flow;
• auto_complete.cpp: interactive line editing, Tab completion vocabulary,

history navigation and command/function suggestions;

• main_aux_processor.cpp and main_processor.cpp: command and expression

routing around the main calculation flow;

• processing_core.cpp: expression processing, arithmetic solving, and

function processing;

• commands.cpp: many user-facing command handlers;
• equation_solver.cpp and equations_system_solver.cpp: equation-solving

paths;

• solver.cpp: numerical solver functionality;
• polynomial_arithmetic.cpp: polynomial simplification and related helpers;
• function_study.cpp: function study workflow;
• dynamic_allocations.cpp: dynamic allocation helpers and tracking support;
• data_processing_core.cpp: data/settings/helper processing used across

multiple features;

• mathematical modules such as trigonometry.cpp, hyperbolic.cpp,

logarithmic.cpp, statistics.cpp, digital_signal_processing.cpp, and related calculation files.

Project-wide declarations are concentrated in stdafx.h and helper headers such as precision_types.h, safe_chararray.h, and safe_index.h.

Command Processing Flow

For a visual overview, see the "Module Architecture and Execution Flow" section in docs/Architecture.md.

At a high level:

1. main.cpp initializes ATC paths/settings and selects double or Boost

mp_float based on persisted precision settings.

2. mainType<T>() enters the typed runtime flow.
3. User input or command-line arguments are routed into the main processing

functions.

4. main_core<T>() and main_sub_core<T>() coordinate commands, variables,

output, and expression evaluation.

5. Mathematical expressions pass through initialProcessor<T>(),

arithSolver<T>(), and functionProcessor<T>() as needed.

The exact route depends on command type, current settings, and whether ATC is running interactively or through redirected/command-line input.

Parser and Expression Evaluation Overview

Expression processing is implemented in the existing C++ parser flow rather than through an external parser library.

The processing core handles:

• arithmetic operators;
• function calls;
• constants such as pi, e, and infinity markers;
• complex values;
• matrix expressions;
• implicit multiplication forms;
• precision-dependent result formatting.

ATC also uses documented syntax conventions such as _ for negative values in some internal/output forms.

Interactive Prompt and Autocomplete

The interactive prompt uses a custom console line editor instead of plain gets_s(...). It supports:

• Tab completion while the user is typing;
• repeated Tab cycling when more than one completion is possible;
• shortest closest-match ordering for command/function suggestions;
• Up/Down history navigation using history.txt;
• Left/Right, Home, End, Delete and Backspace editing;
• suggestions for documented mathematical functions, commands, aliases and

user functions stored under the ATC User functions folder.

The autocomplete path should remain lightweight because it runs during normal typing. Suggestions are cached for the current line so repeated Tab presses do not rebuild the full list unnecessarily.

Equation Solver Overview

ATC supports several equation-related paths:

• quadratic equation command;
• systems of equations command;
• coefficient-form polynomial solving;
• supported textual polynomial normalization;
• selected rational-cancellation fast paths;
• numerical solver workflows through solver(...).

The equation-solver documentation and tests currently validate simple textual polynomials, coefficient lists, high-degree polynomial examples, rational cancellation, and symbolic constants such as pi, e, and complex pii.

Unsupported expressions should remain on existing fallback paths or be rejected clearly rather than being treated as solved.

Precision Mode Overview

ATC 2.1.7 can run using:

• double
• Boost mp_float

The persisted precision setting is stored in:

%USERPROFILE%\Pictures\Advanced Trigonometry Calculator\higherPrecision.txt

Startup reads the persisted value and dispatches the main template flow to the selected numeric type. Some commands also support temporary high-precision evaluation through the documented maxprec prefix.

Memory Considerations

The project uses custom dynamic allocation helpers in dynamic_allocations.cpp. Recent 2.1.7 work reduced unnecessary allocation in several areas and improved release behavior for dynamic arrays.

When changing memory-sensitive code:

• use existing allocation/deletion helpers where appropriate;
• avoid large fixed-size buffers when the input size is known;
• preserve null termination for dynamic character arrays;
• release temporary arrays on all return paths;
• run memory stress tests when practical.

Test Infrastructure

Automated tests live in tests/.

Main scripts:

• run-atc-regression.ps1: broad regression runner;
• run-atc-memory-stress.ps1: repeated memory-sensitive command runner;
• run-atc-script-benchmark.ps1: script throughput and memory benchmark;
• run-atc-isolated-coverage.ps1: helper for isolated coverage scenarios.

Current validated regression result for Release x64 and Release x86:

Summary: 377 passed, 0 failed

Current isolated coverage result:

Summary: 68 passed, 0 failed

See docs/Testing.md for commands and coverage details.

Practical Developer Reference

The dedicated Developer Reference covers:

• how to add a new command;
• how to add a mathematical function;
• how to add a guided module;
• how to add regression tests;
• documentation expectations;
• parser and solver regression risks;
• Windows compatibility considerations;
• output-stability rules;
• pre-commit and pre-release checklist.

Use it together with this guide and the architecture overview before changing parser, solver, console or persistence behavior.

ATC Developer Reference

This reference complements the Developer Guide. It focuses on practical contribution workflows for Advanced Trigonometry Calculator 2.1.7.

Main Project Structure

• Advanced Trigonometry Calculator/: C++ source code and Visual Studio

project files.

• tests/: PowerShell regression, isolated coverage and memory stress tests.
• docs/: Markdown, PDF and DOCX documentation.
• tools/docs/: documentation generation helpers.

Coding Expectations

• Keep public command names stable unless a compatibility plan exists.
• Prefer existing parser, allocation and formatting helpers.
• Keep code comments in English.
• Avoid hidden behavior that cannot be tested or documented.
• Preserve Windows XP to Windows 11 compatibility goals where the current code

supports them.

Adding a New Command

1. Locate the closest existing command handler in commands.cpp,

main_processor.cpp or main_aux_processor.cpp.

2. Follow the existing command-detection style.
3. Keep prompts and outputs stable if they will be tested.
4. Add automated coverage in tests/run-atc-regression.ps1 where possible.
5. Document the command in the user guide and coverage matrix.

Adding a Mathematical Function

1. Check whether the function belongs in trigonometry.cpp, hyperbolic.cpp,

logarithmic.cpp, statistics.cpp, digital_signal_processing.cpp or another existing module.

2. Ensure both double and Boost mp_float paths are considered.
3. Confirm angle-mode behavior if the function is trigonometric.
4. Add autocomplete vocabulary if the function should be suggested.
5. Add regression tests with stable expected output.

Adding a Guided Module

1. Keep the interactive flow deterministic where practical.
2. Avoid opening external windows during automated tests.
3. Add at least a safe smoke test.
4. Document manual validation gaps if full automation is not practical.

Adding a Regression Test

Use tests/run-atc-regression.ps1 for normal command/output checks. Keep tests:

• deterministic;
• independent of local absolute paths;
• safe under redirected input;
• isolated from user settings, or backed up/restored by the runner.

Do not update the documented test count unless the suite has been executed.

Documenting a Feature

When a feature changes:

1. update the English reference document first;
2. review the Portuguese counterpart;
3. update tests/ATC_USER_GUIDE_COVERAGE.md;
4. regenerate PDFs/DOCX when relevant.

Parser and Solver Regression Risks

Parser and solver changes should be tested with:

• direct arithmetic;
• implicit multiplication;
• variables;
• complex values;
• polynomial simplification;
• solve equation(...);
• solver(...);
• high precision mode where relevant.

Avoid solving a special case by bypassing the normal processing flow unless the behavior is deliberately documented and tested.

Windows Compatibility Notes

ATC contains console behavior for old and new Windows environments. Be careful with:

• Windows Terminal specific behavior;
• ANSI/VT color output;
• console window size and position;
• commands that launch new instances, tabs, files or folders.

Output Stability

Automated tests normally match output patterns. Before changing visible output, consider whether it is part of:

• user documentation;
• release notes;
• regression tests;
• exported text reports.

Pre-commit / Pre-release Checklist

• Build Release x64.
• Build Release x86 when compatibility-sensitive code changed.
• Run the regression suite.
• Run isolated coverage if the change touches interactive or source-level

behavior.

• Run memory stress tests for allocation-heavy changes.
• Update documentation and release notes.
• Check Markdown links and regenerate PDFs/DOCX when needed.

Advanced Trigonometry Calculator Testing

This document explains the current test infrastructure for Advanced Trigonometry Calculator (ATC).

Regression Test Runner

The main automated regression runner is:

tests\run-atc-regression.ps1

Run it after building ATC:

powershell -ExecutionPolicy Bypass -File .\tests\run-atc-regression.ps1 -AtcExe .\x64\Release\atc.exe

For x86 builds:

powershell -ExecutionPolicy Bypass -File .\tests\run-atc-regression.ps1 -AtcExe .\Release\atc.exe

Current validated result for both Release x64 and Release x86:

Summary: 377 passed, 0 failed

Latest Release x86 and Release x64 builds completed successfully with 0 Warning(s), 0 Error(s), and both executables passed the same regression suite.

Do not run ATC test runners in parallel against the same ATC data directory. The runners intentionally mutate settings, variables and temporary files under the ATC data folder. Parallel execution is only safe when each ATC process uses an isolated data directory.

Memory Stress Runner

The memory stress runner is:

tests\run-atc-memory-stress.ps1

Example:

powershell -ExecutionPolicy Bypass -File .\tests\run-atc-memory-stress.ps1 -Iterations 10

It currently focuses on repeated polynomial simplification, roots-to-polynomial, and textual/coefficient equation solver commands.

SRS Gate Runner

The SRS gate runner is:

tests\run-atc-srs-gates.ps1

It validates selected measurable requirements from docs\SOFTWARE_REQUIREMENTS_SPECIFICATION.md:

• Stage 1: parser and syntax guard matrix with 50+ valid/malformed inputs;
• Stage 2: precision persistence and startup gate;
• Stage 3: degree-20 polynomial simplification / equation solving latency and

Memory Factor telemetry;

• Stage 4: command bridge / TXT detector fixture with mocked external opening

and unrelated-directory preservation.

Quick validation without the heavy stress loop:

powershell -ExecutionPolicy Bypass -File .\tests\run-atc-srs-gates.ps1 -AtcExe .\x64\Release\atc.exe -SkipStress

Release stress validation:

powershell -ExecutionPolicy Bypass -File .\tests\run-atc-srs-gates.ps1 -AtcExe .\x64\Release\atc.exe -StressIterations 500

Latest short SRS gate validation:

Summary: 4 passed, 0 failed
StressIterations: 2

Isolated Coverage Helper

The isolated coverage helper is:

tests\run-atc-isolated-coverage.ps1

Use it when a specific area needs focused validation outside the full regression run.

Current isolated coverage result:

Summary: 68 passed, 0 failed

Current SourceForge package validation result:

Summary: 44 passed, 0 failed

Current Automated Coverage

The regression suite currently covers:

• arithmetic basics and precedence;
• parser syntax guards for malformed parentheses, empty function arguments,

consecutive operators and invalid operator placement;

• constants and precision formatting;
• trigonometry and inverse trigonometry;
• hyperbolic and inverse hyperbolic functions;
• logarithms and custom guide syntax;
• complex-number paths used by documented commands;
• matrix/list functions, matrix helper commands, direct matrix/vector indexing

and persisted indexed matrix updates;

• variable names and implicit multiplication;
• sorting and ASCII sorting flows;
• roots-to-polynomial report export;
• polynomial simplification;
• equation solving and systems of equations;
• solver paths including selected trigonometric, hyperbolic, polynomial, and

rational-cancellation cases;

• function study examples;
• graph settings, deterministic graph navigation simulation, navigation edge

clamping and explicit graph-range navigation;

• date/time commands that can be automated safely;
• TXT detector / command bridge commands, including redirected CMD input,

mocked shell/window side effects, and real-file solve txt processing with mocked answer-file opening;

• file/folder command existence checks;
• app environment commands that can run safely under redirected input,

including about and auto adjust window;

• variable/result management commands;
• persistent settings and menu retry behavior;
• one safe runtime smoke path for each deep interactive module: unit

conversions, microeconomics, physics, statistics, geometry, financial calculations, triangles rectangles solver, and arithmetic matrix solver;

• verbose-resolution behavior;
• interactive prompt behavior, including Tab autocomplete vocabulary,

ambiguous-match cycling and Up/Down history navigation;

• double and Boost mp_float precision mode persistence.

The detailed test matrix is maintained in:

tests\ATC_AUTOMATED_TEST_CASES.md

Documentation to Test Traceability

Documented behavior should have automated coverage whenever it is deterministic and safe to execute under redirected input.

Use these rules when updating documentation:

• stable command examples should be added to the regression suite where

practical;

• interactive modules should have at least a safe smoke test or an explicit

manual-validation note;

• commands that open windows, files, browsers or PC-control actions should use

mocks, source-level checks or manual validation notes;

• do not update the documented test count unless the suite has actually been

executed;

• update tests\ATC_USER_GUIDE_COVERAGE.md when a documented area gains or

loses coverage.

The Cookbook and Best Practices documents are intended to use already documented commands. If a recipe cannot be tested safely, it should say so through notes or limitations.

Known Manual or Interactive Validation Gaps

The automated suite intentionally avoids or only partially covers:

• shutdown, restart, hibernate, sleep, lock, and similar PC-control commands;
• full-duration clock, stopwatch, timer, and continuously running views;
• commands that open external browsers or editors, except for TXT/file flows

that now have explicit mock coverage;

• full live manual graph rendering and key-buffer behavior;
• remaining branches inside deeply interactive modules such as triangles,

arithmetic matrix solver, conversions, finance, physics, microeconomics, and statistics menus.

Long-running time command branches, short stopwatch marking, zero-duration clock rendering, and timer syntax guards are covered by the isolated helper. Full-duration countdowns, alarms, and continuously running views should still be validated manually or covered later with safe, non-destructive automation.

The direct TXT workflow is covered with temporary fixtures: predefine txt writes a real input path, solve txt generates the _answers.txt response file, invalid lines are kept isolated from later lines, and the answer-file open is recorded through the test mock instead of launching Notepad. The fixture also covers solve equation and simplify polynomial inside the TXT input, including their export-prompt-safe non-interactive path. auto solve txt now has a deterministic runtime fixture that uses a real TXT file containing SOLVE_NOW, verifies that the flag is consumed, validates the generated answer file, and records the answer-file open through the test mock.

SourceForge Package Validation

The package validation runner is:

tests\run-atc-package-validation.ps1

It validates the staged SourceForge package structure without rebuilding the ZIP. Current checks include root files, x64/x86 runtime executables, generated PDF documentation, absence of duplicated source folders, absence of generated answer files, GitHub source notices, and SHA256 checksum consistency for every packaged file.

Example:

powershell -ExecutionPolicy Bypass -File .\tests\run-atc-package-validation.ps1

Settings Modified by Tests

The regression runner may temporarily touch ATC setting files under:

%USERPROFILE%\Pictures\Advanced Trigonometry Calculator

The runner backs up and restores the settings it modifies.

Recommended Validation Before Changes

For most changes:

powershell -ExecutionPolicy Bypass -File .\tests\run-atc-regression.ps1 -AtcExe .\x64\Release\atc.exe

For memory-sensitive work, also run the memory stress runner and the script benchmark when practical.

Script Performance Validation

The script interpreter has additional automated benchmark coverage for the Scripts examples/Multiplication Table 1-100_script_generator.txt workflow. This scenario is useful because it repeatedly exercises:

• nested for loops;
• variable assignment and reuse;
• print("...", ...) formatting;
• repeated scalar expression evaluation inside script output.

ATC 2.1.7 reduces memory pressure in this flow by releasing temporary TXT-processing arrays, avoiding matrix scratch allocation for scalar expressions, executing safe print("...", ...) script lines directly in memory instead of routing them through the temporary TXT-processing file path, and evaluating simple scalar assignments, loop conditions and integer print arguments through a lightweight script path.

Run the benchmark with:

powershell -ExecutionPolicy Bypass -File .\tests\run-atc-script-benchmark.ps1 -AtcExe .\x64\Release\atc.exe

The benchmark validates process exit, elapsed time, peak working set and stable output content. Latest Release x64 validation:

Summary: 4 passed, 0 failed
ElapsedSeconds: 7.41
PeakWorkingSetMB: 119.56