Optimize Concatenate_iterator to O(1) for random access iterators

[atta-ullah01]

Summary of Changes

This PR optimizes CGAL::Concatenate_iterator to provide $O(1)$ time complexity for arithmetic operations (operator+, operator-, operator+=, operator-=) and distance calculations when the underlying iterators are Random Access Iterators (e.g., std::vector, pointers).

Previously, these operations relied on $O(n)$ loops (checking ++ or -- sequentially). This change utilizes C++17 if constexpr to conditionally enable the optimized arithmetic logic while preserving the original $O(n)$ fallback for Forward or Bidirectional iterators (e.g., std::list).

Key Changes:

• $O(1)$ Arithmetic: implemented operator+ and operator- (offset) to calculate positions immediately by checking range boundaries.
• $O(1)$ Distance: Implemented operator- (difference) to calculate the distance between two iterators across the concatenated ranges without traversal.
• Iterator Category Deduction: updated iterator_category to use std::common_type_t. This correctly degrades the category to the "lowest common denominator" (e.g., mixing a Random Access iterator with a Bidirectional iterator results in a Bidirectional Concatenate_iterator).
• Compound Assignment: Added operator+= and operator-=.
• Negative Offsets: Fixed operator+ and operator- to correctly handle negative arguments by delegating to their inverse counterparts.
• Tests: Added comprehensive tests for $O(1)$ behavior using std::vector and regression tests for mixed iterator categories.

This resolves the TODO comments previously located at lines 100 and 116 regarding complexity optimizations.

Release Management

• Affected package(s): STL_Extension
• Issue(s) solved (if any): Resolves internal TODOs regarding $O(1)$ complexity.
• Feature/Small Feature (if any): Optimization for Concatenate_iterator
• Link to compiled documentation (obligatory for small feature):
• License and copyright ownership: CGAL

[Copilot]

Pull request overview

This PR optimizes CGAL::Concatenate_iterator to provide O(1) time complexity for arithmetic operations when the underlying iterators are Random Access Iterators, replacing the previous O(n) loop-based implementations.

Key changes:

• Implements O(1) arithmetic operations (operator+, operator-, operator+=, operator-=) and distance calculations for random access iterators using if constexpr
• Updates iterator category deduction to use std::common_type_t to handle mixed iterator types
• Adds comprehensive tests for O(1) behavior and mixed iterator categories

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 9 comments.

File	Description
STL_Extension/include/CGAL/Concatenate_iterator.h	Implements O(1) arithmetic operations with conditional compilation based on iterator category; adds Traits2 typedef and updates iterator_category deduction
STL_Extension/test/STL_Extension/test_Concatenate_iterator.cpp	Adds tests for O(1) operations with vectors and regression tests for mixed iterator categories

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.