/rust/registry/src/index.crates.io-1949cf8c6b5b557f/ndarray-0.17.2/src/shape_builder.rs

Source
use crate::dimension::IntoDimension;
use crate::order::Order;
use crate::Dimension;

/// A contiguous array shape of n dimensions.
///
/// Either c- or f- memory ordered (*c* a.k.a *row major* is the default).
#[derive(Copy, Clone, Debug)]
pub struct Shape<D>
{
    /// Shape (axis lengths)
    pub(crate) dim: D,
    /// Strides can only be C or F here
    pub(crate) strides: Strides<Contiguous>,
}

#[derive(Copy, Clone, Debug)]
pub(crate) enum Contiguous {}

impl<D> Shape<D>
{
    pub(crate) fn is_c(&self) -> bool
    {
        matches!(self.strides, Strides::C)
    }
}

/// An array shape of n dimensions in c-order, f-order or custom strides.
#[derive(Copy, Clone, Debug)]
pub struct StrideShape<D>
{
    pub(crate) dim: D,
    pub(crate) strides: Strides<D>,
}

impl<D> StrideShape<D>
where D: Dimension
{
    /// Return a reference to the dimension
    pub fn raw_dim(&self) -> &D
    {
        &self.dim
    }
    /// Return the size of the shape in number of elements
    pub fn size(&self) -> usize
    {
        self.dim.size()
    }
}

/// Stride description
#[derive(Copy, Clone, Debug)]
pub(crate) enum Strides<D>
{
    /// Row-major ("C"-order)
    C,
    /// Column-major ("F"-order)
    F,
    /// Custom strides
    Custom(D),
}

impl<D> Strides<D>
{
    /// Return strides for `dim` (computed from dimension if c/f, else return the custom stride)
    pub(crate) fn strides_for_dim(self, dim: &D) -> D
    where D: Dimension
    {
        match self {
            Strides::C => dim.default_strides(),
            Strides::F => dim.fortran_strides(),
            Strides::Custom(c) => {
                debug_assert_eq!(
                    c.ndim(),
                    dim.ndim(),
                    "Custom strides given with {} dimensions, expected {}",
                    c.ndim(),
                    dim.ndim()
                );
                c
            }
        }
    }

    #[inline]
    pub(crate) fn is_custom(&self) -> bool
    {
        matches!(*self, Strides::Custom(_))
    }
}

/// A trait for `Shape` and `D where D: Dimension` that allows
/// customizing the memory layout (strides) of an array shape.
///
/// This trait is used together with array constructor methods like
/// `Array::from_shape_vec`.
pub trait ShapeBuilder
{
    /// The type that captures the built shape's dimensionality.
    type Dim: Dimension;

    /// The type that captures the built shape's stride pattern.
    type Strides;

    /// Turn into a contiguous-element [`Shape`].
    fn into_shape_with_order(self) -> Shape<Self::Dim>;

    /// Convert into a Fortran-order (a.k.a., column-order) [`Shape`].
    fn f(self) -> Shape<Self::Dim>;

    /// Set the order of the shape to either Fortran or non-Fortran.
    fn set_f(self, is_f: bool) -> Shape<Self::Dim>;

    /// Set the strides of the shape.
    fn strides(self, strides: Self::Strides) -> StrideShape<Self::Dim>;
}

impl<D> From<D> for Shape<D>
where D: Dimension
{
    /// Create a `Shape` from `dimension`, using the default memory layout.
    fn from(dimension: D) -> Shape<D>
    {
        dimension.into_shape_with_order()
    }
}

impl<T, D> From<T> for StrideShape<D>
where
    D: Dimension,
    T: ShapeBuilder<Dim = D>,
{
    fn from(value: T) -> Self
    {
        let shape = value.into_shape_with_order();
        let st = if shape.is_c() { Strides::C } else { Strides::F };
        StrideShape {
            strides: st,
            dim: shape.dim,
        }
    }
}

impl<T> ShapeBuilder for T
where T: IntoDimension
{
    type Dim = T::Dim;
    type Strides = T;
    fn into_shape_with_order(self) -> Shape<Self::Dim>
    {
        Shape {
            dim: self.into_dimension(),
            strides: Strides::C,
        }
    }
    fn f(self) -> Shape<Self::Dim>
    {
        self.set_f(true)
    }
    fn set_f(self, is_f: bool) -> Shape<Self::Dim>
    {
        self.into_shape_with_order().set_f(is_f)
    }
    fn strides(self, st: T) -> StrideShape<Self::Dim>
    {
        self.into_shape_with_order().strides(st.into_dimension())
    }
}

impl<D> ShapeBuilder for Shape<D>
where D: Dimension
{
    type Dim = D;
    type Strides = D;

    fn into_shape_with_order(self) -> Shape<D>
    {
        self
    }

    fn f(self) -> Self
    {
        self.set_f(true)
    }

    fn set_f(mut self, is_f: bool) -> Self
    {
        self.strides = if !is_f { Strides::C } else { Strides::F };
        self
    }

    fn strides(self, st: D) -> StrideShape<D>
    {
        StrideShape {
            dim: self.dim,
            strides: Strides::Custom(st),
        }
    }
}

impl<D> Shape<D>
where D: Dimension
{
    /// Return a reference to the dimension
    pub fn raw_dim(&self) -> &D
    {
        &self.dim
    }
    /// Return the size of the shape in number of elements
    pub fn size(&self) -> usize
    {
        self.dim.size()
    }
}

/// Array shape argument with optional order parameter
///
/// Shape or array dimension argument, with optional [`Order`] parameter.
///
/// This is an argument conversion trait that is used to accept an array shape and
/// (optionally) an ordering argument.
///
/// See for example [`.to_shape()`](crate::ArrayRef::to_shape).
pub trait ShapeArg
{
    /// The type that captures the shape's dimensionality.
    type Dim: Dimension;

    /// Convert the argument into a shape and an [`Order`].
    fn into_shape_and_order(self) -> (Self::Dim, Option<Order>);
}

impl<T> ShapeArg for T
where T: IntoDimension
{
    type Dim = T::Dim;

    fn into_shape_and_order(self) -> (Self::Dim, Option<Order>)
    {
        (self.into_dimension(), None)
    }
}

impl<T> ShapeArg for (T, Order)
where T: IntoDimension
{
    type Dim = T::Dim;

    fn into_shape_and_order(self) -> (Self::Dim, Option<Order>)
    {
        (self.0.into_dimension(), Some(self.1))
    }
}

Coverage Report

Created: 2026-03-31 07:09

Line	Count	Source
1		use crate::dimension::IntoDimension;
2		use crate::order::Order;
3		use crate::Dimension;
4
5		/// A contiguous array shape of n dimensions.
6		///
7		/// Either c- or f- memory ordered (c a.k.a row major is the default).
8		#[derive(Copy, Clone, Debug)]
9		pub struct Shape<D>
10		{
11		/// Shape (axis lengths)
12		pub(crate) dim: D,
13		/// Strides can only be C or F here
14		pub(crate) strides: Strides<Contiguous>,
15		}
16
17		#[derive(Copy, Clone, Debug)]
18		pub(crate) enum Contiguous {}
19
20		impl<D> Shape<D>
21		{
22	0	pub(crate) fn is_c(&self) -> bool
23		{
24	0	matches!(self.strides, Strides::C)
25	0	} Unexecuted instantiation: <ndarray::shape_builder::Shape<ndarray::dimension::dim::Dim<[usize; 1]>>>::is_c Unexecuted instantiation: <ndarray::shape_builder::Shape<_>>::is_c
26		}
27
28		/// An array shape of n dimensions in c-order, f-order or custom strides.
29		#[derive(Copy, Clone, Debug)]
30		pub struct StrideShape<D>
31		{
32		pub(crate) dim: D,
33		pub(crate) strides: Strides<D>,
34		}
35
36		impl<D> StrideShape<D>
37		where D: Dimension
38		{
39		/// Return a reference to the dimension
40	0	pub fn raw_dim(&self) -> &D
41		{
42	0	&self.dim
43	0	}
44		/// Return the size of the shape in number of elements
45	0	pub fn size(&self) -> usize
46		{
47	0	self.dim.size()
48	0	}
49		}
50
51		/// Stride description
52		#[derive(Copy, Clone, Debug)]
53		pub(crate) enum Strides<D>
54		{
55		/// Row-major ("C"-order)
56		C,
57		/// Column-major ("F"-order)
58		F,
59		/// Custom strides
60		Custom(D),
61		}
62
63		impl<D> Strides<D>
64		{
65		/// Return strides for `dim` (computed from dimension if c/f, else return the custom stride)
66	0	pub(crate) fn strides_for_dim(self, dim: &D) -> D
67	0	where D: Dimension
68		{
69	0	match self {
70	0	Strides::C => dim.default_strides(),
71	0	Strides::F => dim.fortran_strides(),
72	0	Strides::Custom(c) => {
73	0	debug_assert_eq!(
74	0	c.ndim(),
75	0	dim.ndim(),
76		"Custom strides given with {} dimensions, expected {}",
77	0	c.ndim(),
78	0	dim.ndim()
79		);
80	0	c
81		}
82		}
83	0	} Unexecuted instantiation: <ndarray::shape_builder::Strides<ndarray::dimension::dim::Dim<[usize; 1]>>>::strides_for_dim Unexecuted instantiation: <ndarray::shape_builder::Strides<_>>::strides_for_dim
84
85		#[inline]
86	0	pub(crate) fn is_custom(&self) -> bool
87		{
88	0	matches!(*self, Strides::Custom(_))
89	0	}
90		}
91
92		/// A trait for `Shape` and `D where D: Dimension` that allows
93		/// customizing the memory layout (strides) of an array shape.
94		///
95		/// This trait is used together with array constructor methods like
96		/// `Array::from_shape_vec`.
97		pub trait ShapeBuilder
98		{
99		/// The type that captures the built shape's dimensionality.
100		type Dim: Dimension;
101
102		/// The type that captures the built shape's stride pattern.
103		type Strides;
104
105		/// Turn into a contiguous-element [`Shape`].
106		fn into_shape_with_order(self) -> Shape<Self::Dim>;
107
108		/// Convert into a Fortran-order (a.k.a., column-order) [`Shape`].
109		fn f(self) -> Shape<Self::Dim>;
110
111		/// Set the order of the shape to either Fortran or non-Fortran.
112		fn set_f(self, is_f: bool) -> Shape<Self::Dim>;
113
114		/// Set the strides of the shape.
115		fn strides(self, strides: Self::Strides) -> StrideShape<Self::Dim>;
116		}
117
118		impl<D> From<D> for Shape<D>
119		where D: Dimension
120		{
121		/// Create a `Shape` from `dimension`, using the default memory layout.
122	0	fn from(dimension: D) -> Shape<D>
123		{
124	0	dimension.into_shape_with_order()
125	0	}
126		}
127
128		impl<T, D> From<T> for StrideShape<D>
129		where
130		D: Dimension,
131		T: ShapeBuilder<Dim = D>,
132		{
133	0	fn from(value: T) -> Self
134		{
135	0	let shape = value.into_shape_with_order();
136	0	let st = if shape.is_c() { Strides::C } else { Strides::F };
137	0	StrideShape {
138	0	strides: st,
139	0	dim: shape.dim,
140	0	}
141	0	} Unexecuted instantiation: <ndarray::shape_builder::StrideShape<ndarray::dimension::dim::Dim<[usize; 1]>> as core::convert::From<ndarray::dimension::dim::Dim<[usize; 1]>>>::from Unexecuted instantiation: <ndarray::shape_builder::StrideShape<ndarray::dimension::dim::Dim<[usize; 1]>> as core::convert::From<ndarray::shape_builder::Shape<ndarray::dimension::dim::Dim<[usize; 1]>>>>::from Unexecuted instantiation: <ndarray::shape_builder::StrideShape<ndarray::dimension::dim::Dim<[usize; 1]>> as core::convert::From<usize>>::from Unexecuted instantiation: <ndarray::shape_builder::StrideShape<_> as core::convert::From<_>>::from
142		}
143
144		impl<T> ShapeBuilder for T
145		where T: IntoDimension
146		{
147		type Dim = T::Dim;
148		type Strides = T;
149	0	fn into_shape_with_order(self) -> Shape<Self::Dim>
150		{
151	0	Shape {
152	0	dim: self.into_dimension(),
153	0	strides: Strides::C,
154	0	}
155	0	} Unexecuted instantiation: <ndarray::dimension::dim::Dim<[usize; 1]> as ndarray::shape_builder::ShapeBuilder>::into_shape_with_order Unexecuted instantiation: <[usize; 1] as ndarray::shape_builder::ShapeBuilder>::into_shape_with_order Unexecuted instantiation: <usize as ndarray::shape_builder::ShapeBuilder>::into_shape_with_order Unexecuted instantiation: <_ as ndarray::shape_builder::ShapeBuilder>::into_shape_with_order
156	0	fn f(self) -> Shape<Self::Dim>
157		{
158	0	self.set_f(true)
159	0	}
160	0	fn set_f(self, is_f: bool) -> Shape<Self::Dim>
161		{
162	0	self.into_shape_with_order().set_f(is_f)
163	0	} Unexecuted instantiation: <ndarray::dimension::dim::Dim<[usize; 1]> as ndarray::shape_builder::ShapeBuilder>::set_f Unexecuted instantiation: <_ as ndarray::shape_builder::ShapeBuilder>::set_f
164	0	fn strides(self, st: T) -> StrideShape<Self::Dim>
165		{
166	0	self.into_shape_with_order().strides(st.into_dimension())
167	0	} Unexecuted instantiation: <ndarray::dimension::dim::Dim<[usize; 1]> as ndarray::shape_builder::ShapeBuilder>::strides Unexecuted instantiation: <[usize; 1] as ndarray::shape_builder::ShapeBuilder>::strides Unexecuted instantiation: <_ as ndarray::shape_builder::ShapeBuilder>::strides
168		}
169
170		impl<D> ShapeBuilder for Shape<D>
171		where D: Dimension
172		{
173		type Dim = D;
174		type Strides = D;
175
176	0	fn into_shape_with_order(self) -> Shape<D>
177		{
178	0	self
179	0	} Unexecuted instantiation: <ndarray::shape_builder::Shape<ndarray::dimension::dim::Dim<[usize; 1]>> as ndarray::shape_builder::ShapeBuilder>::into_shape_with_order Unexecuted instantiation: <ndarray::shape_builder::Shape<_> as ndarray::shape_builder::ShapeBuilder>::into_shape_with_order
180
181	0	fn f(self) -> Self
182		{
183	0	self.set_f(true)
184	0	}
185
186	0	fn set_f(mut self, is_f: bool) -> Self
187		{
188	0	self.strides = if !is_f { Strides::C } else { Strides::F };
189	0	self
190	0	} Unexecuted instantiation: <ndarray::shape_builder::Shape<ndarray::dimension::dim::Dim<[usize; 1]>> as ndarray::shape_builder::ShapeBuilder>::set_f Unexecuted instantiation: <ndarray::shape_builder::Shape<_> as ndarray::shape_builder::ShapeBuilder>::set_f
191
192	0	fn strides(self, st: D) -> StrideShape<D>
193		{
194	0	StrideShape {
195	0	dim: self.dim,
196	0	strides: Strides::Custom(st),
197	0	}
198	0	} Unexecuted instantiation: <ndarray::shape_builder::Shape<ndarray::dimension::dim::Dim<[usize; 1]>> as ndarray::shape_builder::ShapeBuilder>::strides Unexecuted instantiation: <ndarray::shape_builder::Shape<_> as ndarray::shape_builder::ShapeBuilder>::strides
199		}
200
201		impl<D> Shape<D>
202		where D: Dimension
203		{
204		/// Return a reference to the dimension
205	0	pub fn raw_dim(&self) -> &D
206		{
207	0	&self.dim
208	0	}
209		/// Return the size of the shape in number of elements
210	0	pub fn size(&self) -> usize
211		{
212	0	self.dim.size()
213	0	}
214		}
215
216		/// Array shape argument with optional order parameter
217		///
218		/// Shape or array dimension argument, with optional [`Order`] parameter.
219		///
220		/// This is an argument conversion trait that is used to accept an array shape and
221		/// (optionally) an ordering argument.
222		///
223		/// See for example [`.to_shape()`](crate::ArrayRef::to_shape).
224		pub trait ShapeArg
225		{
226		/// The type that captures the shape's dimensionality.
227		type Dim: Dimension;
228
229		/// Convert the argument into a shape and an [`Order`].
230		fn into_shape_and_order(self) -> (Self::Dim, Option<Order>);
231		}
232
233		impl<T> ShapeArg for T
234		where T: IntoDimension
235		{
236		type Dim = T::Dim;
237
238	0	fn into_shape_and_order(self) -> (Self::Dim, Option<Order>)
239		{
240	0	(self.into_dimension(), None)
241	0	}
242		}
243
244		impl<T> ShapeArg for (T, Order)
245		where T: IntoDimension
246		{
247		type Dim = T::Dim;
248
249	0	fn into_shape_and_order(self) -> (Self::Dim, Option<Order>)
250		{
251	0	(self.0.into_dimension(), Some(self.1))
252	0	}
253		}