# diagm

diagm(v[, k])

Construct a diagonal matrix and place `v` on the `k`th diagonal.

## Examples

1. Create a diagonal matrix:

``````julia> v = [1, 2, 3];
julia> diagm(v)
3×3 Array{Int64,2}:
1  0  0
0  2  0
0  0  3``````

This example creates a diagonal matrix using the elements of vector `v`.

2. Place vector on a specific diagonal:

``````julia> v = [4, 5];
julia> diagm(v, 1)
3×3 Array{Int64,2}:
0  4  0
0  0  5
0  0  0``````

The `k` argument specifies the diagonal index where the elements of vector `v` will be placed. In this example, the vector `v` is placed on the first diagonal.

3. Negative index for lower diagonals:
``````julia> v = [6, 7];
julia> diagm(v, -1)
3×3 Array{Int64,2}:
0  0  0
6  0  0
0  7  0``````

Using a negative value for `k` places the vector `v` on a lower diagonal.

Common mistake example:

``````julia> v = [1, 2, 3, 4];
julia> diagm(v, 2)
ERROR: DimensionMismatch("invalid index: 2, matrix has size (4, 4)")``````

In this example, the vector `v` has more elements than the size of the resulting diagonal matrix. Make sure the length of the vector does not exceed the number of rows or columns in the resulting matrix.