Implement permutedims

docs/src/man/reshaping_and_pivoting.md

@@ -392,7 +392,7 @@ julia> df1 = DataFrame(a=["x", "y"], b=[1.0, 2.0], c=[3, 4], d=[true, false])
 │ 1   │ x      │ 1.0     │ 3     │ 1    │
 │ 2   │ y      │ 2.0     │ 4     │ 0    │
 
-julia> permutedims(df1)
+julia> permutedims(df1, 1)
 3×3 DataFrame
 │ Row │ a      │ x       │ y       │
 │     │ String │ Float64 │ Float64 │
@@ -402,12 +402,15 @@ julia> permutedims(df1)
 │ 3   │ d      │ 1.0     │ 0.0     │
 ```
 
-Note that the first column (by default) of the original `df`
+Note that the column indexed by `src_colnames` in the original `df`
 becomes the column names in the permuted result,
 and the column names of the original become a new column.
 Typically, this would be used on columns with homogenous element types,
 since the element types of the other columns
 are the result of `promote_type` on _all_ the permuted columns.
+Note also that, by default, the new column created from the column names
+of the original `df` has the same name as `src_namescol`.
+An optional positional argument `dest_namescol` can alter this:
 
 ```jldoctest reshape
 julia> df2 = DataFrame(a=["x", "y"], b=[1, "two"], c=[3, 4], d=[true, false])
@@ -418,12 +421,12 @@ julia> df2 = DataFrame(a=["x", "y"], b=[1, "two"], c=[3, 4], d=[true, false])
 │ 1   │ x      │ 1   │ 3     │ 1    │
 │ 2   │ y      │ two │ 4     │ 0    │
 
-julia> permutedims(df2)
+julia> permutedims(df2, 1, "different_name")
 3×3 DataFrame
-│ Row │ a      │ x   │ y   │
-│     │ String │ Any │ Any │
-├─────┼────────┼─────┼─────┤
-│ 1   │ b      │ 1   │ two │
-│ 2   │ c      │ 3   │ 4   │
-│ 3   │ d      │ 1   │ 0   │
+│ Row │ different_name │ x   │ y   │
+│     │ String         │ Any │ Any │
+├─────┼────────────────┼─────┼─────┤
+│ 1   │ b              │ 1   │ two │
+│ 2   │ c              │ 3   │ 4   │
+│ 3   │ d              │ 1   │ 0   │
 ```

src/abstractdataframe/reshape.jl

@@ -417,7 +417,7 @@ with name specified by `dest_namescol`.
 # Arguments
 - `df` : the `AbstractDataFrame`
 - `src_namescol` : the column that will become the new header.
-  This column's element type must be `AbstractString` or `Symbol`.
+  This column's element type must be `AbstractString`, `Symbol`, or `Int`.
 - `dest_namescol` : the name of the first column in the returned `DataFrame`.
   Defaults to the same name as `src_namescol`.
 - `makeunique` : if `false` (the default), an error will be raised
@@ -443,14 +443,6 @@ julia> df1 = DataFrame(a=["x", "y"], b=[1., 2.], c=[3, 4], d=[true,false])
 │ 1   │ x      │ 1.0     │ 3     │ 1    │
 │ 2   │ y      │ 2.0     │ 4     │ 0    │
 
-julia> df2 = DataFrame(a=["x", "y"], b=[1, "two"], c=[3, 4], d=[true, false])
-2×4 DataFrame
-│ Row │ a      │ b   │ c     │ d    │
-│     │ String │ Any │ Int64 │ Bool │
-├─────┼────────┼─────┼───────┼──────┤
-│ 1   │ x      │ 1   │ 3     │ 1    │
-│ 2   │ y      │ two │ 4     │ 0    │
-
 julia> permutedims(df1, 1) # note the column types
 3×3 DataFrame
 │ Row │ a      │ x       │ y       │
@@ -460,14 +452,22 @@ julia> permutedims(df1, 1) # note the column types
 │ 2   │ c      │ 3.0     │ 4.0     │
 │ 3   │ d      │ 1.0     │ 0.0     │
 
-julia> permutedims(df2, 1)
+julia> df2 = DataFrame(a=["x", "y"], b=[1, "two"], c=[3, 4], d=[true, false])
+2×4 DataFrame
+│ Row │ a      │ b   │ c     │ d    │
+│     │ String │ Any │ Int64 │ Bool │
+├─────┼────────┼─────┼───────┼──────┤
+│ 1   │ x      │ 1   │ 3     │ 1    │
+│ 2   │ y      │ two │ 4     │ 0    │
+
+julia> permutedims(df2, 1, "different_name")
 3×3 DataFrame
-│ Row │ a      │ x   │ y   │
-│     │ String │ Any │ Any │
-├─────┼────────┼─────┼─────┤
-│ 1   │ b      │ 1   │ two │
-│ 2   │ c      │ 3   │ 4   │
-│ 3   │ d      │ 1   │ 0   │
+│ Row │ different_name │ x   │ y   │
+│     │ String         │ Any │ Any │
+├─────┼────────────────┼─────┼─────┤
+│ 1   │ b              │ 1   │ two │
+│ 2   │ c              │ 3   │ 4   │
+│ 3   │ d              │ 1   │ 0   │
 ```
 """
 function Base.permutedims(df::AbstractDataFrame, src_namescol::ColumnIndex,