Current state of affairs

There is currently a lot of inconsistencies between diagm and spdiagm. Some methods of diagm and its behavior:

• diagm(v::AbstractVector, k): place vector v on the kth diagonal
• diagm(v::SparseMatrixCSC): Note SparseMatrixCSC, not SparseVector, and it has to be of size (n,1) or (1,n). This places places the entries on the 0th diagonal (no choice).
• diagm(v::BitMatrix): Same thing here, matrix of size (n,1) or (1,n) and no choice of placement.

spdiagm is a bit more flexible: we can supply multiple vectors for multiple diagonals, e.g. spdiagm((v1, v2), (k1,k2)) places vector v1 and v2 on diagonal k1 and k2 respectively. We can also specify the resulting matrix size, e.g. spdiagm((v1, v2), (k1,k2), m, n) which will create a m×n matrix. Is this actually useful? Looking at the code, it seems like its there to kind of mirror the sparse(I,J,V) / sparse(I,J,V,m,n) methods.

Action plan

The most obvious things are:

• Deprecate diagm(A::SparseMatrixCSC) in favor of spdiagm(sparsevec(A)) (deprecate diagm(A::SparseMatrixCSC) in favor of spdiagm(sparsevec(A)) #23341)
• Deprecate diagm(A::BitMatrix) in favor of diagm(vec(A)) (deprecate diagm(A::BitMatrix) #23373)

Change to nicer Pair API instead of the diagm(tuple_of_vecs, tuple_of_diags) methods.

• Deprecate spdiagm(tuple_of_vecs, tuple_of_diags) in favor of spdiagm(p::Pair{<:Integer,<:AbstractVector}...) (Rewrite spdiagm with pairs #23757)
• Implement diagm(p::Pair{<:Integer,<:AbstractVector}...) to match the spdiagm method. (rewrite diagm with Pair's #24047)

Then some other things:

• Remove the option to supply resulting matrix size for spdiagm and always return a square matrix like diagm. (Rewrite spdiagm with pairs #23757)

So when we are here, we have diagm and spdiagm that match each other. Where could we go from here? We delete spdiagm! 🎉

• Deprecate spdiagm(vecs, diags) in favor of diagm(sparsevec.(vecs), diags)

So now we only have diagm. Lets delete that too?

• Deprecate diagm(v::AbstractVector) in favor of Matrix(Diagonal(v))
• Deprecate diagm(v::SparseVector) in favor of sparse(Diagonal(v))
• Deprecate diagm(v::BitVector) in favor of BitMatrix(Diagonal(v))

The only problem with this is that we can't really specify diagonals easily anymore, and lose the option to supply more than one vector. So perhaps this last step was just too much.