

   MMaattrriixx DDiiaaggoonnaallss

        diag(x, nrow, ncol)
        diag(x) <- value

   VVaalluuee::

        If `x' is a matrix then `diag(x)' returns the diagonal
        of `x'.  If `x' is a vector then `x' returns a diagonal
        matrix whose diagonal is `x'.  If `x' is an integer
        then `diag(x)' returns an identity matrix of order `x'.
        The dimension of the returned matrix can be specified
        by `nrow' and `ncol' (the default is square).

        The assignment form sets the diagonal of the matrix `x'
        to the given value(s).

   SSeeee AAllssoo::

        `matrix'.

   EExxaammpplleess::

        dim(diag(3))
        diag(10,3,4) # guess what?
        all(diag(1:3) == {m <- matrix(0,3,3); diag(m) <- 1:3; m})

