Rename (and move) transpose to permute_dims

spec/API_specification/array_object.md

@@ -274,7 +274,7 @@ Transpose of the array.
 The array instance must be two-dimensional. If the array instance is not two-dimensional, an error should be raised.
 
 ```{note}
-Limiting the transpose to two-dimensional arrays (matrices) deviates from the NumPy et al practice of reversing all axes for arrays having more than two-dimensions. This is intentional, as reversing all axes was found to be problematic (e.g., conflicting with the mathematical definition of a transpose which is limited to matrices; not operating on batches of matrices; et cetera). In order to reverse all axes, one is recommended to use the functional `permute` interface found in this specification.
+Limiting the transpose to two-dimensional arrays (matrices) deviates from the NumPy et al practice of reversing all axes for arrays having more than two-dimensions. This is intentional, as reversing all axes was found to be problematic (e.g., conflicting with the mathematical definition of a transpose which is limited to matrices; not operating on batches of matrices; et cetera). In order to reverse all axes, one is recommended to use the functional `permute_dims` interface found in this specification.
 ```
 
 #### Returns

spec/API_specification/manipulation_functions.md

@@ -80,6 +80,27 @@ Reverses the order of elements in an array along the given axis. The shape of th
 
     -   an output array having the same data type and shape as `x` and whose elements, relative to `x`, are reordered.
 
+(function-permute-dims)=
+### permute_dims(x, /, axes)
+
+Permutes the axes (dimensions) of an array `x`.
+
+#### Parameters
+
+-   **x**: _<array>_
+
+    -   input array.
+
+-   **axes**: _Tuple\[ int, ... ]_
+
+    -   tuple containing a permutation of `(0, 1, ..., N-1)` where `N` is the number of axes (dimensions) of `x`.
+
+#### Returns
+
+-   **out**: _<array>_
+
+    -   an array containing the axes permutation. The returned array must have the same data type as `x`.
+
 (function-reshape)=
 ### reshape(x, /, shape)