docs cleanup - part 1

Author: SpectraL519

docs/core_util_types.md

@@ -9,7 +9,6 @@ This section describes a set of fundamental types provided by the library. While
 - [Common type traits](#common-type-traits)
 - [General type aliases](#general-type-aliases)
 - [Graph element property types](#graph-element-property-types)
-- [Iterator-related types](#iterator-related-types)
 - [I/O types](#io-types)
 
 <br />
@@ -33,9 +32,6 @@ The table below contains the basic type aliases defined in the library.
 | `size_type` | `std::uint64_t` |
 | `id_type` | `size_type` |
 | `homogeneous_pair<T>` | `std::pair<T, T>` |
-| `optional_ref<T>` | `std::optional<std::reference_wrapper<std::remove_reference_t<T>>>` |
-| `optional_cref` | `std::optional<std::reference_wrapper<const std::remove_cvref_t<T>>>` |
-| `const_ref_wrap` | `std::reference_wrapper<const T>` |
 
 > [!NOTE]
 > All types in the table above are defined in the `gl::types` namespace and in the [gl/types/types.hpp](/include/gl/types/types.hpp) header file.
@@ -251,257 +247,6 @@ This section describes the type traits that are associated with the property typ
 <br />
 <br />
 
-## Iterator-related types
-
-This section provides the description of types used to manage range/collection iterators.
-
-### `class iterator_range`
-
-- *Description*:
-  The `iterator_range` class is a wrapper around a pair of forward iterators, providing a range interface with optional caching behavior. It allows for efficient iteration over a range of elements, with different caching strategies based on the specified `CacheMode`.
-
-- *Template parameters*:
-  - `Iterator: std::forward_iterator` - A type that meets the requirements of a forward iterator.
-  - `CacheMode: type_traits::c_cache_mode` - A type trait that defines the caching strategy.
-    **NOTE:** The `CacheMode` parameter can be one of the following: `gl::type_traits::{no_cache,lazy_cache,eager_cache}`
-
-> [!IMPORTANT]
-> The default caching strategy for the `iterator_range` class can be set using the following macros:
->
-> - `GL_CONFIG_IT_RANGE_DEFAULT_CACHE_MODE_EAGER` - default strategy set to `gl::type_traits::eager_cache`
-> - `GL_CONFIG_IT_RANGE_DEFAULT_CACHE_MODE_LAZY` - default strategy set to `gl::type_traits::lazy_cache`
-> - `GL_CONFIG_IT_RANGE_DEFAULT_CACHE_MODE_NONE` - default strategy set to `gl::type_traits::no_cache`
-
-- *Type definitions*:
-  - `iterator` - The type of the iterator.
-  - `const_iterator` - The type of the constant iterator **(for C++23 or newer)**.
-  - `distance_type` - The type used for representing the distance between iterators (`std::ptrdiff_t`).
-  - `value_type` - The type of the elements in the range (equivalent to `std::remove_reference_t<typename iterator::value_type>`).
-  - `cache_mode` - The caching strategy used in the range (an alias for `CacheMode`).
-
-- *Constructors*:
-  - `iterator_range(iterator begin, iterator end)` - Initializes the iterator range using the specified caching strategy.
-  - `iterator_range(const iterator_range&)` - Copy constructor (*default*).
-  - `iterator_range(iterator_range&&)` - Move constructor (*default*).
-
-- *Assignment operators*:
-  - `operator=(const iterator_range&)` - Copy assignment operator (*default*).
-  - `operator=(iterator_range&&)` - Move assignment operator (*default*).
-
-- *Destructor*:
-  - `~iterator_range()` - Destructor (*default*).
-
-- *Member functions*:
-  - `begin() const -> iterator` - Returns an iterator to the beginning of the range.
-  - `end() const -> iterator` - Returns an iterator to the end of the range.
-  - `cbegin() const -> auto` - Returns a constant iterator to the beginning of the range **(for C++23 or newer)**.
-  - `cend() const -> auto` - Returns a constant iterator to the end of the range **(for C++23 or newer)**.
-  - `distance() const -> distance_type` - Returns the number of elements in the range, computed based on the caching strategy.
-  - `element_at(types::size_type position) -> value_type&` - Returns a reference to the element at the specified position.
-  - `element_at(types::size_type position) const -> const value_type&` - Returns a reference to the element at the specified position.
-  - `operator[](types::size_type position) -> value_type&` - Provides access to the element at the specified position (equivalent to `element_at`).
-  - `operator[](types::size_type position) const -> const value_type&` - Provides access to the element at the specified position (equivalent to `element_at`).
-
-> [!IMPORTANT]
-> The `iterator_range` class is marked `final` by default. To use this class as a base class you have to add:
->
-> ```cpp
-> #define GL_CONFIG_IT_RANGE_NOT_FINAL
-> ```
->
-> in your program or add a `-DGL_CONFIG_IT_RANGE_NOT_FINAL` flag when compiling.
-
-#### Associated functions
-
-- `gl::make_iterator_range(begin, end)`
-  - *Description*: Creates an `iterator_range` from the given iterators using the specified caching strategy.
-  - *Template parameters*:
-    - `Iterator: std::forward_iterator` - The iterator type.
-    - `CacheMode: type_traits::c_cache_mode` - The caching strategy.
-  - *Parameters*:
-    - `begin: Iterator` - the begin iterator
-    - `end: Iterator` - the end iterator
-  - *Return type*: `types::iterator_range<Iterator, CacheMode>`
-
-- `gl::make_iterator_range(range)`
-  - *Description*: Creates an `iterator_range` from the given range using its `begin` and `end` iterators and with the specified caching strategy
-  - *Template parameters*:
-    - `Range: c_range` - The range type.
-    - `CacheMode: type_traits::c_cache_mode` - The caching strategy.
-  - *Parameters*:
-    - `range: Range&` - the range used to create the `iterator_range`
-  - *Return type*: `types::iterator_range<typename Range::iterator, CacheMode>`
-
-- `gl::make_const_iterator_range(range)`
-  - *Description*: Creates an `iterator_range` from the given range using its `cbegin` and `cend` iterators and with the specified caching strategy
-  - *Template parameters*:
-    - `Range: c_range` - The range type.
-    - `CacheMode: type_traits::c_cache_mode` - The caching strategy.
-  - *Parameters*:
-    - `range: const Range&` - the range used to create the `iterator_range`
-  - *Return type*: `types::iterator_range<typename Range::const_iterator, CacheMode>`
-
-<br />
-
-### `class dereferencing_iterator`
-
-- *Description*:
-  The `dereferencing_iterator` class is a wrapper around a forward iterator that dereferences its elements, providing direct access to the underlying objects managed by strong pointer types. This iterator enables seamless iteration over collections of pointer elements.
-
-- *Template parameters*:
-  - `Iterator: std::forward_iterator` - A type that meets the requirements of a forward iterator and points to strong pointer types.
-
-- *Constraints*:
-  - `type_traits::c_strong_ptr<typename Iterator::value_type>` - The iterator's value type must be a strong (raw, unique, shared) pointer type.
-
-- *Type definitions*:
-  - `iterator_type` - The type of the underlying iterator.
-  - `value_type` - The type of the elements pointed to by the strong pointers (defined as `type_traits::ptr_element_type_t<iterator_value_type>`).
-  - `reference` - A reference type to the dereferenced value (`value_type&`).
-  - `pointer` - A pointer type to the dereferenced value (`value_type*`).
-  - `difference_type` - The type used for representing the distance between iterators (inferred from `iterator_type`).
-  - `iterator_category` - The iterator category inferred from `iterator_type`.
-
-- *Constructors*:
-  - `dereferencing_iterator() = default` - Default constructor.
-  - `dereferencing_iterator(iterator_type it)` - Initializes the iterator with the specified iterator.
-  - `dereferencing_iterator(const dereferencing_iterator&) = default` - Copy constructor (*default*).
-  - `dereferencing_iterator(dereferencing_iterator&&) = default` - Move constructor (*default*).
-
-- *Assignment operators*:
-  - `dereferencing_iterator& operator=(const dereferencing_iterator&) = default` - Copy assignment operator (*default*).
-  - `dereferencing_iterator& operator=(dereferencing_iterator&&) = default` - Move assignment operator (*default*).
-
-- *Member functions*:
-  - `operator*() const -> reference` - Dereferences the iterator, returning a reference to the underlying value.
-  - `operator->() const -> pointer` - Returns a pointer to the underlying value, handling strong smart pointer types appropriately.
-  - `operator++() -> dereferencing_iterator&` - Prefix increment operator; advances the iterator.
-  - `operator++(int) -> dereferencing_iterator` - Postfix increment operator; advances the iterator and returns a copy of the previous state.
-  - `operator--() -> dereferencing_iterator&` (requires `std::bidirectional_iterator`) - Prefix decrement operator; moves the iterator backward.
-  - `operator--(int) -> dereferencing_iterator` (requires `std::bidirectional_iterator`) - Postfix decrement operator; moves the iterator backward and returns a copy of the previous state.
-  - `operator==(const dereferencing_iterator& other) const -> bool` - Compares two dereferencing iterators for equality.
-  - `operator!=(const dereferencing_iterator& other) const -> bool` - Compares two dereferencing iterators for inequality.
-  - `base() const -> iterator_type` - Returns the underlying iterator.
-
-#### Associated functions
-
-- `gl::deref_begin(Range& range)`
-  - *Description*: Returns a `dereferencing_iterator` pointing to the beginning of the specified range.
-  - *Template parameters*:
-    - `Range: c_range` - The range type.
-  - *Parameters*:
-    - `range: Range&` - The range from which to obtain the beginning iterator.
-  - *Return type*: `types::dereferencing_iterator<decltype(std::ranges::begin(range))>`
-
-- `gl::deref_end(Range& range)`
-  - *Description*: Returns a `dereferencing_iterator` pointing to the end of the specified range.
-  - *Template parameters*:
-    - `Range: c_range` - The range type.
-  - *Parameters*:
-    - `range: Range&` - The range from which to obtain the end iterator.
-  - *Return type*: `types::dereferencing_iterator<decltype(std::ranges::end(range))>`
-
-- `gl::deref_cbegin(const Range& range)`
-  - *Description*: Returns a `dereferencing_iterator` pointing to the constant beginning of the specified range.
-  - *Template parameters*:
-    - `Range: c_const_range` - The constant range type.
-  - *Parameters*:
-    - `range: const Range&` - The range from which to obtain the constant beginning iterator.
-  - *Return type*: `types::dereferencing_iterator<decltype(std::ranges::cbegin(range))>`
-
-- `gl::deref_cend(const Range& range)`
-  - *Description*: Returns a `dereferencing_iterator` pointing to the constant end of the specified range.
-  - *Template parameters*:
-    - `Range: c_const_range` - The constant range type.
-  - *Parameters*:
-    - `range: const Range&` - The range from which to obtain the constant end iterator.
-  - *Return type*: `types::dereferencing_iterator<decltype(std::ranges::cend(range))>`
-
-<br />
-
-### `class non_null_iterator`
-
-- *Description*:
-  The `non_null_iterator` class is a wrapper around a forward iterator that skips null elements (i.e., null pointers) during iteration. This iterator is particularly useful when working with collections of pointers where you want to ignore any null values seamlessly.
-
-- *Template parameters*:
-  - `Iterator: std::forward_iterator` - A type that meets the requirements of a forward iterator and points to strong pointer types.
-
-- *Constraints*:
-  - `type_traits::c_strong_ptr<typename Iterator::value_type>` - The iterator's value type must be a strong (raw, unique, shared) pointer type.
-
-- *Type definitions*:
-  - `iterator_type` - The type of the underlying iterator.
-  - `value_type` - The type of the elements pointed to by the strong pointers (inferred from `iterator_type`).
-  - `reference` - The reference type of the elements in the underlying iterator (`typename std::iterator_traits<iterator_type>::reference`).
-  - `pointer` - The pointer type of the elements in the underlying iterator (`typename std::iterator_traits<iterator_type>::pointer`).
-  - `difference_type` - The type used for representing the distance between iterators (inferred from `iterator_type`).
-  - `iterator_category` - The iterator category inferred from `iterator_type`.
-
-- *Constructors*:
-  - `non_null_iterator() = default` - Default constructor.
-  - `non_null_iterator(iterator_type current, iterator_type end)` (for non-bidirectional iterators) - Initializes the iterator with the specified current and end iterators, skipping initial null elements if necessary.
-  - `non_null_iterator(iterator_type begin, iterator_type current, iterator_type end)` (for bidirectional iterators) - Initializes the iterator with specified begin, current, and end iterators, skipping initial null elements if necessary.
-  - `non_null_iterator(const non_null_iterator&) = default` - Copy constructor (*default*).
-  - `non_null_iterator(non_null_iterator&&) = default` - Move constructor (*default*).
-
-- *Assignment operators*:
-  - `non_null_iterator& operator=(const non_null_iterator&) = default` - Copy assignment operator (*default*).
-  - `non_null_iterator& operator=(non_null_iterator&&) = default` - Move assignment operator (*default*).
-
-- *Member functions*:
-  - `operator*() const -> reference` - Dereferences the iterator, returning a reference to the underlying non-null value.
-  - `operator->() const -> pointer` - Returns a pointer to the underlying non-null value.
-  - `operator++() -> non_null_iterator&` - Prefix increment operator; advances the iterator and skips any subsequent null elements.
-  - `operator++(int) -> non_null_iterator` - Postfix increment operator; advances the iterator and skips any subsequent null elements, returning a copy of the previous state.
-  - `operator--() -> non_null_iterator&` (requires `std::bidirectional_iterator`) - Prefix decrement operator; moves the iterator backward and skips any null elements.
-  - `operator--(int) -> non_null_iterator` (requires `std::bidirectional_iterator`) - Postfix decrement operator; moves the iterator backward and skips any null elements, returning a copy of the previous state.
-  - `operator==(const non_null_iterator& other) const -> bool` - Compares two non-null iterators for equality.
-  - `operator!=(const non_null_iterator& other) const -> bool` - Compares two non-null iterators for inequality.
-  - `base() const -> iterator_type` - Returns the current underlying iterator.
-
-- *Private member functions*:
-  - `_is_null(const reference& ptr) -> bool` - Checks if the given pointer is null.
-  - `_skip_null_elements_forward()` - Advances the current iterator past any null elements in the forward direction.
-  - `_skip_null_elements_backward()` (requires `std::bidirectional_iterator`) - Advances the current iterator past any null elements in the backward direction.
-
-#### Associated functions
-
-- `gl::non_null_begin(Range& range)`
-  - *Description*: Returns a `non_null_iterator` pointing to the beginning of the specified range while skipping null elements.
-  - *Template parameters*:
-    - `Range: c_range` - The range type.
-  - *Parameters*:
-    - `range: Range&` - The range from which to obtain the beginning iterator.
-  - *Return type*: `types::non_null_iterator<decltype(std::ranges::begin(range))>`
-
-- `gl::non_null_end(Range& range)`
-  - *Description*: Returns a `non_null_iterator` pointing to the end of the specified range while skipping null elements.
-  - *Template parameters*:
-    - `Range: c_range` - The range type.
-  - *Parameters*:
-    - `range: Range&` - The range from which to obtain the end iterator.
-  - *Return type*: `types::non_null_iterator<decltype(std::ranges::end(range))>`
-
-- `gl::non_null_cbegin(const Range& range)`
-  - *Description*: Returns a `non_null_iterator` pointing to the constant beginning of the specified range while skipping null elements.
-  - *Template parameters*:
-    - `Range: c_const_range` - The constant range type.
-  - *Parameters*:
-    - `range: const Range&` - The range from which to obtain the constant beginning iterator.
-  - *Return type*: `types::non_null_iterator<decltype(std::ranges::cbegin(range))>`
-
-- `gl::non_null_cend(const Range& range)`
-  - *Description*: Returns a `non_null_iterator` pointing to the constant end of the specified range while skipping null elements.
-  - *Template parameters*:
-    - `Range: c_const_range` - The constant range type.
-  - *Parameters*:
-    - `range: const Range&` - The range from which to obtain the constant end iterator.
-  - *Return type*: `types::non_null_iterator<decltype(std::ranges::cend(range))>`
-
-<br />
-<br />
-
 ## I/O types
 
 This section provides the description of I/O types and utility defined in the library.

docs/dev_notes.md

@@ -4,26 +4,25 @@ Here you can find the necessery information to be able to work on the project
 
 <br />
 
-## Building and testing
+## Building and Testing
 
 > [!NOTE]
 > The project uses [doctest](https://github.com/doctest/doctest) framework for unit testing, however it is already installed in the [tests/external](/tests/external/) directory, so there is no need to install it sepparately.
 
-### Build the testing executable
+### Build the testing executables
 
 ```shell
-cmake -B build
-cd build
-make # -j <n>
+cmake -B build -DBUILD_TESTS=ON
+cmake --build build # -j<n>
 ```
 
-This will build the test executable `run` in the `<project-root>/build/tests` directory.
+This will build the test executables `gl` (GL module tests) and `hgl` (HGL module tests) in the `<project-root>/build/tests` directory.
 
 ### Run the tests
 
 ```shell
-cd build
-./tests/run # -ts=<test-suite-name>
+./build/tests/gl  # -ts=<test-suite-name>
+./build/tests/hgl # -ts=<test-suite-name>
 ```
 
 > [!NOTE]