add type alias in direction module and depreciated IteratorDirection

CHANGELOG.md

@@ -39,6 +39,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,15 +13,59 @@ 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::{IteratorDirection, Direction, IteratorElement};
+/// # use lattice_qcd_rs::lattice::{IteratorDirection, OrientedDirection, IteratorElement};
 /// # use lattice_qcd_rs::error::ImplementationError;
 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
-/// let mut iter = IteratorDirection::<4, true>::new(None)
+/// let mut iter = IteratorDirection::<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::{IteratorDirectionOriented, Direction, IteratorElement};
+/// # use lattice_qcd_rs::error::ImplementationError;
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// let mut iter = IteratorDirectionOriented::<4, true>::new(None)
 ///     .ok_or(ImplementationError::OptionWithUnexpectedNone)?;
 /// assert_eq!(
 ///     iter.next()
@@ -47,9 +92,10 @@ 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.
@@ -66,10 +112,10 @@ impl<const D: usize, const IS_POSITIVE_DIRECTION: bool>
     /// after `element`. Giving `None` results in the first element being the direction with index 0
     /// # Example
     /// ```
-    /// # use lattice_qcd_rs::lattice::{IteratorDirection, Direction, IteratorElement};
+    /// # use lattice_qcd_rs::lattice::{IteratorDirectionOriented, Direction, IteratorElement};
     /// # use lattice_qcd_rs::error::ImplementationError;
     /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
-    /// let mut iter = IteratorDirection::<4, true>::new(None)
+    /// let mut iter = IteratorDirectionOriented::<4, true>::new(None)
     ///     .ok_or(ImplementationError::OptionWithUnexpectedNone)?;
     /// assert_eq!(
     ///     iter.next()
@@ -83,7 +129,7 @@ impl<const D: usize, const IS_POSITIVE_DIRECTION: bool>
     /// );
     /// let element =
     ///     Direction::<4>::new(0, false).ok_or(ImplementationError::OptionWithUnexpectedNone)?;
-    /// let mut iter = IteratorDirection::<4, false>::new(Some(element))
+    /// let mut iter = IteratorDirectionOriented::<4, false>::new(Some(element))
     ///     .ok_or(ImplementationError::OptionWithUnexpectedNone)?;
     /// assert_eq!(
     ///     iter.next()
@@ -99,13 +145,13 @@ impl<const D: usize, const IS_POSITIVE_DIRECTION: bool>
     /// # }
     /// ```
     /// ```
-    /// # use lattice_qcd_rs::lattice::{IteratorDirection, Direction, IteratorElement};
+    /// # use lattice_qcd_rs::lattice::{IteratorDirectionOriented, Direction, IteratorElement};
     /// # use lattice_qcd_rs::error::ImplementationError;
     /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
-    /// let iter = IteratorDirection::<0, true>::new(None);
+    /// let iter = IteratorDirectionOriented::<0, true>::new(None);
     /// // 0 is invalid
     /// assert!(iter.is_none());
-    /// let iter = IteratorDirection::<4, true>::new(Some(
+    /// let iter = IteratorDirectionOriented::<4, true>::new(Some(
     ///     Direction::new(2, false).ok_or(ImplementationError::OptionWithUnexpectedNone)?,
     /// ));
     /// // the sign of the direction is invalid
@@ -122,16 +168,17 @@ impl<const D: usize, const IS_POSITIVE_DIRECTION: bool>
         }
     }
 
-    /// create a new iterator. The first call to [`IteratorDirection::next()`] gives the element
+    /// create a new iterator. The first call to [`IteratorDirectionOriented::next()`] gives the element
     /// just after the one given or the first element if [`IteratorElement::FirstElement`]
     /// is given.
     /// # Example
     /// ```
-    /// # use lattice_qcd_rs::lattice::{IteratorDirection, Direction, IteratorElement};
+    /// # use lattice_qcd_rs::lattice::{IteratorDirectionOriented, Direction, IteratorElement};
     /// # use lattice_qcd_rs::error::ImplementationError;
     /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
-    /// let mut iter = IteratorDirection::<4, true>::new_from_element(IteratorElement::FirstElement)
-    ///     .ok_or(ImplementationError::OptionWithUnexpectedNone)?;
+    /// let mut iter =
+    ///     IteratorDirectionOriented::<4, true>::new_from_element(IteratorElement::FirstElement)
+    ///         .ok_or(ImplementationError::OptionWithUnexpectedNone)?;
     /// assert_eq!(
     ///     iter.next()
     ///         .ok_or(ImplementationError::OptionWithUnexpectedNone)?,
@@ -145,7 +192,7 @@ impl<const D: usize, const IS_POSITIVE_DIRECTION: bool>
     /// let element =
     ///     Direction::<4>::new(0, false).ok_or(ImplementationError::OptionWithUnexpectedNone)?;
     /// let mut iter =
-    ///     IteratorDirection::<4, false>::new_from_element(IteratorElement::Element(element))
+    ///     IteratorDirectionOriented::<4, false>::new_from_element(IteratorElement::Element(element))
     ///         .ok_or(ImplementationError::OptionWithUnexpectedNone)?;
     /// assert_eq!(
     ///     iter.next()

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;

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> {