[R45-T019] Document complexity and measure scaling of HeapElement - #59

Description

Documents the complexity of HeapElement in src/main/java/com/thealgorithms/datastructures/heaps/HeapElement.java (naming input-size variable N and distinguishing worst-case O(1)-per-element bounds from JVM wall-clock observations), adds one representative regression test to HeapElementTest.java, adds the scaling and correctness experiment HeapElementScalingTest.java, and adds work/R45-T019/check.py (with timings and evidence saved strictly in work/R45-T019/). All existing behavior and public interfaces are preserved.

Related Issue

Fixes: #19

Type of Change

• Bug Fix
• New Feature
• UI/UX Improvement
• Performance Improvement
• Tests
• Documentation
• Refactoring / Maintenance
• CI/CD

Changes Made

• Added complexity Javadoc in src/main/java/com/thealgorithms/datastructures/heaps/HeapElement.java (lines 23–31): for N HeapElement instances, constructors, getKey(), and getInfo() take O(1) worst-case time and space per element (O(N) total work, 3 field operations per element in the experiment), distinguishing this worst-case bound from observed per-element wall-clock variance due to JIT warmup and allocation/GC, and noting toString(), equals(), and hashCode() add O(1) key work plus additionalInfo's method cost.
• Added testSmallestAndOrdinaryContractAndHashCode() to src/test/java/com/thealgorithms/datastructures/heaps/HeapElementTest.java (lines 57–70), checking (0.0, null) and (5.0, "Info") with literal expected values (0.0/null/"Key: 0.0 - No additional info"/0, and 5.0/"Info"/"Key: 5.0 - Info"/2283881).
• Added src/test/java/com/thealgorithms/datastructures/heaps/HeapElementScalingTest.java with 2 test methods:
  • Smallest valid input (0.0, null) and ordinary input (5.0, "Info") with hand-calculated literal expected outputs and precondition line citations.
  • Seeded scaling experiment (FIXED_SEED = 20261111L, 5 repetitions per size for N in {1000, 10000, 100000}): times only construction + getKey() + getInfo() outside input generation and verification, checks every constructed element outside the timed interval, asserts deterministic operation count 3 * N, and imposes no wall-clock pass/fail threshold.
• Added work/R45-T019/check.py (with evidence files in work/R45-T019/), running mvn test for HeapElementScalingTest, enforcing a nonzero test count, saving comparisons.txt, timings.txt, result.txt, mvn_output.txt, and tool_versions.txt, and exiting non-zero on failure.

Screenshots / Recordings

Not applicable (no UI changes).

Testing

Command: python3 work/R45-T019/check.py
(runs mvn -B test -Dtest=HeapElementScalingTest -Dsurefire.failIfNoSpecifiedTests=false)

Result: tests=2 failures/errors=0 skipped=0 comparisons=5 timings=3 mvn_exit=0, status=PASS

Observed scaling (work/R45-T019/timings.txt, 5 repetitions per size):

• N = 1,000: ops = 3,000, median = 46,083 ns, range = 40,584 ns (45,583..86,167 ns), 46.08 ns/elem
• N = 10,000: ops = 30,000, median = 447,333 ns, range = 365,751 ns (113,541..479,292 ns), 44.73 ns/elem
• N = 100,000: ops = 300,000, median = 1,108,875 ns, range = 117,167 ns (1,104,500..1,221,667 ns), 11.09 ns/elem

Normal suite: mvn -B test -Dtest=HeapElementTest -Dsurefire.failIfNoSpecifiedTests=false → Tests run: 6, Failures: 0, Errors: 0, Skipped: 0 (BUILD SUCCESS).

Negative check: temporarily changing this.key = key; to this.key = key + 1; on line 48 caused python3 work/R45-T019/check.py to print status=FAIL (tests=2 failures/errors=2 skipped=0 mvn_exit=1) and exit non-zero; reverted and re-verified.

Style: mvn -B checkstyle:check reports 0 Checkstyle violations (BUILD SUCCESS).

Tool versions, comparisons, and timings are saved in work/R45-T019/tool_versions.txt, work/R45-T019/comparisons.txt, and work/R45-T019/timings.txt.

Checklist

• I have tested my changes locally.
• I have added or updated tests, if needed.
• I have updated documentation, if needed.
• I have followed the project's coding guidelines.
• I have run the relevant tests and checks.
• I have addressed previous review feedback, if applicable.

Additional Notes

• Timings are kept strictly inside work/R45-T019/timings.txt (excluded from source code), and no pass/fail threshold depends on wall-clock timing.

• The work/R45-T019/ evidence folder is for coursework review only and should not go into any later upstream PR.

• I have read CONTRIBUTING.md.

• This pull request is all my own work -- I have not plagiarized it.

• All filenames are in PascalCase.

• All functions and variable names follow Java naming conventions.

• All new algorithms have a URL in their comments that points to Wikipedia or other similar explanations.

• All new algorithms include a corresponding test class that validates their functionality.

• All new code is formatted with clang-format -i --style=file path/to/your/file.java