add type alias in direction module and depreciated IteratorDirection

Author: ABouttefeux

CHANGELOG.md

@@ -45,6 +45,9 @@
 - added [`LatticeCyclic::par_iter_links`] and [`LatticeCyclic::par_iter_points`] to get parallel iterator on the links and points respectively.
 - Added [`CardinalDirection`].
 - Added [`Axis`].
+- Added type alias [`lattice::IteratorOrientedDirection`] for [`DoubleEndedCounter<OrientedDirection>`].
+- Depreciate [`IteratorDirection`], use [`IteratorOrientedDirection`].
+
 
 # v0.2.1
 

src/lattice/iterator/direction.rs

@@ -3,6 +3,7 @@
 //! # example
 //! see [`IteratorDirection`]
 
+#![allow(deprecated)]
 use std::iter::FusedIterator;
 
 use rayon::iter::{
@@ -12,9 +13,53 @@ use rayon::iter::{
 #[cfg(feature = "serde-serialize")]
 use serde::{Deserialize, Serialize};
 
-use super::{super::Direction, IteratorElement, RandomAccessIterator};
+use super::{super::Direction, DoubleEndedCounter, IteratorElement};
+use crate::lattice::OrientedDirection;
 
-/// Iterator over [`Direction`] with the same sign.
+/// Iterator over [`OrientedDirection`].
+/// # Example
+/// ```
+/// # use lattice_qcd_rs::lattice::{IteratorOrientedDirection, OrientedDirection, IteratorElement};
+/// # use lattice_qcd_rs::error::ImplementationError;
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// let mut iter = IteratorOrientedDirection::<4, true>::new();
+///
+/// let iter_val = iter.next();
+/// // debug
+/// println!("{iter_val:?}, {:?}", OrientedDirection::<4, true>::new(0));
+///
+/// assert_eq!(
+///     iter_val.ok_or(ImplementationError::OptionWithUnexpectedNone)?,
+///     OrientedDirection::<4, true>::new(0)
+///         .ok_or(ImplementationError::OptionWithUnexpectedNone)?
+/// );
+/// assert_eq!(
+///     iter.next()
+///         .ok_or(ImplementationError::OptionWithUnexpectedNone)?,
+///     OrientedDirection::<4, true>::new(1)
+///         .ok_or(ImplementationError::OptionWithUnexpectedNone)?
+/// );
+/// assert_eq!(
+///     iter.next()
+///         .ok_or(ImplementationError::OptionWithUnexpectedNone)?,
+///     OrientedDirection::<4, true>::new(2)
+///         .ok_or(ImplementationError::OptionWithUnexpectedNone)?
+/// );
+/// assert_eq!(
+///     iter.next()
+///         .ok_or(ImplementationError::OptionWithUnexpectedNone)?,
+///     OrientedDirection::<4, true>::new(3)
+///         .ok_or(ImplementationError::OptionWithUnexpectedNone)?
+/// );
+/// assert_eq!(iter.next(), None);
+/// assert_eq!(iter.next(), None);
+/// # Ok(())
+/// # }
+/// ```
+pub type IteratorOrientedDirection<const D: usize, const ORIENTATION: bool> =
+    DoubleEndedCounter<OrientedDirection<D, ORIENTATION>>;
+
+/// Iterator over [`Direction`] with the orientation.
 /// # Example
 /// ```
 /// # use lattice_qcd_rs::lattice::{IteratorDirection, Direction, IteratorElement};
@@ -47,9 +92,13 @@ use super::{super::Direction, IteratorElement, RandomAccessIterator};
 /// # Ok(())
 /// # }
 /// ```
-// TODO
+// TODO remove ?
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Hash)]
 #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
+#[deprecated(
+    since = "0.3.0",
+    note = "use `IteratorOrientedDirection` instead with a map and a conversion"
+)]
 pub struct IteratorDirection<const D: usize, const IS_POSITIVE_DIRECTION: bool> {
     /// Front element of the iterator. The state need to be increased before
     /// being returned by the next [`Iterator::next`] call.

src/lattice/iterator/double_ended_counter.rs

@@ -110,9 +110,10 @@ impl<D: DirectionIndexing> RandomAccessIterator for DoubleEndedCounter<D> {
     type Item = D;
 
     fn iter_len(&self) -> usize {
-        self.front()
+        // this time it is end - front because we use index and not length
+        self.end()
             .direction_to_index()
-            .saturating_sub(self.end().direction_to_index())
+            .saturating_sub(self.front().direction_to_index())
     }
 
     fn increase_front_element_by(&self, advance_by: usize) -> IteratorElement<Self::Item> {

src/lattice/iterator/mod.rs

@@ -28,7 +28,8 @@ mod producer;
 //---------------------------------------
 // uses
 
-pub use self::direction::IteratorDirection;
+#[allow(deprecated)]
+pub use self::direction::{IteratorDirection, IteratorOrientedDirection};
 pub use self::double_ended_counter::DoubleEndedCounter;
 pub use self::element::IteratorElement;
 pub use self::lattice_iterator::LatticeIterator;
@@ -76,12 +77,12 @@ pub trait RandomAccessIterator: Sealed {
     // }
 }
 
-/// Trait used by [`producer::LatticeProducer`] for implementing
+/// Trait used by [`producer::Prod`] for implementing
 /// [`rayon::iter::plumbing::Producer`].
 /// It is separate trait than [`RandomAccessIterator`] to avoid more a [`Clone`] constrain.
 ///
-/// [`Split::split_at`] return two self and not two [`producer::LatticeProducer`] the idea is that they
-/// should be converted into [`producer::LatticeProducer`].
+/// [`Split::split_at`] return two self and not two [`producer::Prod`] the idea is that they
+/// should be converted into [`producer::Prod`].
 ///
 /// This trait is a super trait of [`Sealed`] which is private meaning that It can't be
 /// implemented outside of this trait.

src/lattice/iterator/parallel_iterator.rs

@@ -49,7 +49,7 @@ impl<T> ParIter<T> {
     }
 
     /// Take a reference of self and return a reference to an [`Iterator`].
-    /// This might not be very useful look instead at [`Self::as_iter_mut`]
+    /// This might not be very useful look instead at [`Self::iter_mut`]
     #[must_use]
     #[inline]
     pub const fn as_iter(&self) -> &T {

src/lattice/iterator/producer.rs

@@ -1,4 +1,4 @@
-//! Contains [`LatticeProducer`]
+//! Contains [`Prod`]
 
 //---------------------------------------
 // uses
@@ -10,8 +10,8 @@ use super::{ParIter, RandomAccessIterator, Split};
 //---------------------------------------
 // struct definition
 
-/// [`rayon::iter::plumbing::Producer`] for the [`rayon::iter::IndexedParallelIterator`] [`super::ParIter`] based on
-/// the [`DoubleEndedIterator`] [`LatticeIterator`].
+/// [`rayon::iter::plumbing::Producer`] for the [`rayon::iter::IndexedParallelIterator`]
+/// [`super::ParIter`] based on the [`DoubleEndedIterator`] [`Prod`].
 #[repr(transparent)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct Prod<T>(T);
@@ -25,21 +25,21 @@ impl<T> Prod<T> {
         Self(iter)
     }
 
-    /// Convert self into a [`LatticeIterator`]
+    /// Convert self into a [`Prod`]
     #[inline]
     #[must_use]
     pub fn into_iterator(self) -> T {
         self.0
     }
 
-    /// Convert as a reference of [`LatticeIterator`]
+    /// Convert as a reference of [`Prod`]
     #[inline]
     #[must_use]
     const fn as_iter(&self) -> &T {
         &self.0
     }
 
-    /// Convert as a mutable reference of [`LatticeIterator`]
+    /// Convert as a mutable reference of [`Prod`]
     #[allow(clippy::iter_not_returning_iterator)] // yes in some cases (see impl of IntoIterator)
     #[inline]
     #[must_use]

src/lattice/mod.rs

@@ -27,9 +27,11 @@ pub use self::direction::{
     Axis, Direction, DirectionConversionError, DirectionEnum, DirectionList, OrientedDirection,
 };
 // TODO remove IteratorElement from public interface ?
+#[allow(deprecated)]
 pub use self::iterator::{
     IteratorDirection, IteratorElement, IteratorLatticeLinkCanonical, IteratorLatticePoint,
-    LatticeIterator, ParIter, ParIterLatticeLinkCanonical, ParIterLatticePoint,
+    IteratorOrientedDirection, LatticeIterator, ParIter, ParIterLatticeLinkCanonical,
+    ParIterLatticePoint,
 };
 pub use self::lattice_cyclic::LatticeCyclic;
 use crate::private::Sealed;
@@ -524,6 +526,7 @@ impl<const D: usize> LatticeLinkCanonical<D> {
         self.dir = dir.to_positive();
     }
 
+    /// Transform an index to an canonical link inside a given lattice if it exists
     #[inline]
     #[must_use]
     fn index_to_canonical_link(lattice: &LatticeCyclic<D>, index: usize) -> Option<Self> {