tests for matrix splice and transpose; normalize capitalization and punctuation

Author: Alex-Jordan

lib/Value/Matrix.pm

@@ -839,19 +839,28 @@ sub twiddle {
 
 =head3 C<slice>
 
-Produce the degree (n-1) Matrix defined by a given index and value for that index. If n is 1,
-this produces a Real/Complex/Fraction.
+Produce the degree (n-1) Matrix defined by a given index (the first, second, ..., nth) and a
+value for that index along that dimension. If n is 1, this produces a Real/Complex/Fraction.
 
 Usage:
 
     $A = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ] ]);
-    $A->slice(1, 2)            # will be same as Matrix([5, 6, 7, 8])
-    $A->slice(2, 3)            # will be same as Matrix([3, 7, 11])
+    $A->slice(1, 2)
+    # Index 1 identifies the 1st, 2nd, or 3rd row above, and with value 2 we get the second one:
+    # Matrix([5, 6, 7, 8])
 
     $B = Matrix([ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ]);
-    $B->slice(1, 2)            # will be same as Matrix([ [ 5, 6 ], [ 7, 8 ] ])
-    $B->slice(2, 1)            # will be same as Matrix([ [ 1, 2 ], [ 5, 6 ] ])
-    $B->slice(3, 1)            # will be same as Matrix([ [ 1, 3 ], [ 5, 7 ] ])
+    $B->slice(1, 2)
+    # Index 1 identifies the two arrays at depth 1, and with value 2 we get the second one:
+    # Matrix([ [ 5, 6 ], [ 7, 8 ] ])
+    $B->slice(2, 1)
+    # Here we take all entries from $B where the 2nd index is 1: the 1 at position (1,1,1),
+    # the 2 at position (1,1,2), the 5 at position (2,1,1), and the 6 at position (2,1,2):
+    # Matrix([ [ 1, 2 ], [ 5, 6 ] ])
+    $B->slice(3, 1)
+    # Here we take all entries from $B where the 3rd index is 1: the 1 at position (1,1,1),
+    # the 3 at position (1,2,1), the 5 at position (2,1,1), and the 7 at position (2,2,1):
+    # Matrix([ [ 1, 3 ], [ 5, 7 ] ])
 
 =cut
 
@@ -885,14 +894,41 @@ specified, the default is the usual transposition of the last two indices.
 
 Usage:
 
-    $A = Matrix([ [ 1, 2, 3, 4 ], [ 5, 6, 7, 8 ], [ 9, 10, 11, 12 ] ]);
-    $A->transpose              # will be [ [ 1, 5, 9 ], [ 2, 6, 10 ], [ 3, 7, 11 ], [ 4, 8, 12 ] ]
-
-    $B = Matrix([ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ]);
-    $B->transpose([1, 2, 3])   # will be [ [ [ 1, 3 ], [ 5, 7 ] ], [ [2 , 4 ], [ 6, 8 ] ] ]
-
-    $C = Matrix([ [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ], [ [ [ 9, A ], [ B, C ] ], [ [ D, E ], [ F, 0 ] ] ] ]);
-    $C->transpose([ [ 1, 2], [3, 4] ])   # will be [ [ [ [ 1, 3 ], [ 2, 4 ] ], [ [ 9, B ], [ A, C ] ] ], [ [ [ 5, 7 ], [ 6, 8 ] ], [ [ D, F ], [ E, 0 ] ] ]
+    $A = Matrix([
+        [ 1,  2,  3,  4 ],
+        [ 5,  6,  7,  8 ],
+        [ 9, 10, 11, 12 ]
+    ]);
+    $A->transpose
+    # will be
+    # [
+    #     [ 1, 5, 9 ],
+    #     [ 2, 6, 10 ],
+    #     [ 3, 7, 11 ],
+    #     [ 4, 8, 12 ]
+    # ]
+
+    $B = Matrix([
+        [ [ 1, 2 ], [ 3, 4 ] ],
+        [ [ 5, 6 ], [ 7, 8 ] ]
+    ]);
+    $B->transpose([1, 2, 3])
+    # will be
+    # [
+    #     [ [ 1, 3 ], [ 5, 7 ] ],
+    #     [ [ 2, 4 ], [ 6, 8 ] ]
+    # ]
+
+    $C = Matrix([
+        [ [ [ 1,  2 ], [  3,  4 ] ], [ [  5,  6 ], [  7,  8 ] ] ],
+        [ [ [ 9, 10 ], [ 11, 12 ] ], [ [ 13, 14 ], [ 15, 16 ] ] ]
+    ]);
+    $C->transpose([ [ 1, 2], [3, 4] ])
+    # will be
+    # [
+    #     [ [ [ 1, 3 ], [ 2, 4 ] ], [ [  9, 11 ], [ 10, 12 ] ] ],
+    #     [ [ [ 5, 7 ], [ 6, 8 ] ], [ [ 13, 15 ], [ 14, 16 ] ] ]
+    # ]
 =cut
 
 sub transpose {