feat: 实现转置变换及测试文档全覆盖

Signed-off-by: YdrMaster <ydrml@hotmail.com>

src/lib.rs

@@ -1,3 +1,6 @@
+#![doc = include_str!("../README.md")]
+#![deny(warnings, missing_docs)]
+
 mod transform;
 
 use std::{
@@ -9,6 +12,7 @@ use std::{
 
 pub use transform::{IndexArg, SliceArg, Split, TileArg, TileOrder};
 
+/// A tensor layout allow N dimensions inlined.
 pub struct TensorLayout<const N: usize = 2> {
     order: usize,
     content: Union<N>,

src/transform/index.rs

@@ -1,10 +1,13 @@
 use crate::TensorLayout;
 use std::iter::zip;
 
-#[derive(Debug)]
+/// 索引变换参数。
+#[derive(Clone, PartialEq, Eq, Debug)]
 pub struct IndexArg {
-    axis: usize,
-    index: usize,
+    /// 索引的轴。
+    pub axis: usize,
+    /// 选择指定轴的第几个元素。
+    pub index: usize,
 }
 
 impl<const N: usize> TensorLayout<N> {

src/transform/mod.rs

@@ -3,6 +3,7 @@ mod merge;
 mod slice;
 mod split;
 mod tile;
+mod transpose;
 
 pub use index::IndexArg;
 pub use slice::SliceArg;

src/transform/slice.rs

@@ -1,11 +1,16 @@
 use crate::TensorLayout;
 use std::iter::zip;
 
-#[derive(Clone, PartialEq, Eq, Hash, Debug)]
+/// 切片变换参数。
+#[derive(Clone, PartialEq, Eq, Debug)]
 pub struct SliceArg {
+    /// 切片的轴。
     pub axis: usize,
+    /// 切片的起始位置。
     pub start: usize,
+    /// 切片的步长。
     pub step: isize,
+    /// 切片的长度。
     pub len: usize,
 }
 

src/transform/split.rs

@@ -1,5 +1,6 @@
 use crate::TensorLayout;
 
+/// 切分变换参数。
 pub struct Split<'a, const N: usize> {
     src: &'a TensorLayout<N>,
     axis: usize,

src/transform/tile.rs

@@ -1,16 +1,23 @@
 use crate::TensorLayout;
 use std::iter::zip;
 
-#[derive(Clone, PartialEq, Eq, Hash, Debug)]
+/// 分块变换参数。
+#[derive(Clone, PartialEq, Eq, Debug)]
 pub struct TileArg<'a> {
+    /// 分块的轴。
     pub axis: usize,
+    /// 分块的顺序。
     pub order: TileOrder,
+    /// 分块的大小。
     pub tiles: &'a [usize],
 }
 
+/// 分块顺序。
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub enum TileOrder {
+    /// 大端分块，分块后范围更大的维度在形状中更靠前的位置。
     BigEndian,
+    /// 小端分块，分块后范围更小的维度在形状中更靠前的位置。
     LittleEndian,
 }
 

src/transform/transpose.rs

@@ -0,0 +1,43 @@
+use crate::TensorLayout;
+use std::{collections::BTreeSet, iter::zip};
+
+impl<const N: usize> TensorLayout<N> {
+    /// 转置变换允许调换张量的维度顺序，但不改变元素的存储顺序。
+    ///
+    /// ```rust
+    /// # use tensor::TensorLayout;
+    /// let layout = TensorLayout::<3>::new(&[2, 3, 4], &[12, 4, 1], 0).transpose(&[1, 0]);
+    /// assert_eq!(layout.shape(), &[3, 2, 4]);
+    /// assert_eq!(layout.strides(), &[4, 12, 1]);
+    /// assert_eq!(layout.offset(), 0);
+    /// ```
+    pub fn transpose(&self, perm: &[usize]) -> Self {
+        let perm_ = perm.iter().collect::<BTreeSet<_>>();
+        assert_eq!(perm_.len(), perm.len());
+
+        let content = self.content();
+        let shape = content.shape();
+        let strides = content.strides();
+
+        let ans = Self::with_order(self.order);
+        let content = ans.content();
+        content.set_offset(self.offset());
+        let set = |i, j| {
+            content.set_shape(i, shape[j]);
+            content.set_stride(i, strides[j]);
+        };
+
+        let mut last = 0;
+        for (&i, &j) in zip(perm_, perm) {
+            for i in last..i {
+                set(i, i);
+            }
+            set(i, j);
+            last = i + 1;
+        }
+        for i in last..shape.len() {
+            set(i, i);
+        }
+        ans
+    }
+}