\HeaderA{printSpMatrix}{Print Sparse Matrices Flexibly}{printSpMatrix}
\aliasA{printSpMatrix2}{printSpMatrix}{printSpMatrix2}
\keyword{print}{printSpMatrix}
\begin{Description}\relax
Print sparse matrices flexibly. These are the \dQuote{workhorses} used by
the \code{\LinkA{show}{show}} and \code{\LinkA{print}{print}} methods for sparse
matrices.  If \code{x} is large, \code{printSpMatrix2(x)} calls
\code{printSpMatrix()} twice, namely, for the first and the last few
rows, suppressing those in between, and also suppresses columns when
\code{x} is too wide.
\end{Description}
\begin{Usage}
\begin{verbatim}
printSpMatrix(x, digits = getOption("digits"), maxp = getOption("max.print"),
              zero.print = ".", col.names, note.dropping.colnames = TRUE,
              col.trailer = "",
              align = c("fancy", "right"))

printSpMatrix2(x, digits = getOption("digits"), maxp = getOption("max.print"),
              zero.print = ".", col.names, note.dropping.colnames = TRUE,
              suppRows = NULL, suppCols = NULL,
              col.trailer = if(suppCols) "......" else "",
              align = c("fancy", "right"))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] an \R{} object inheriting from class \code{\LinkA{sparseMatrix}{sparseMatrix.Rdash.class}}.
\item[\code{digits}] significant digits to use for printing, see
\code{\LinkA{print.default}{print.default}}.
\item[\code{maxp}] integer, default from \code{\LinkA{options}{options}(max.print)},
influences how many entries of large matrices are printed at all.
\item[\code{zero.print}] character which should be printed for
\emph{structural} zeroes.  The default \code{"."} may occasionally
be replaced by \code{" "} (blank); using \code{"0"} would look
almost like \code{print()}ing of non-sparse matrices.
\item[\code{col.names}] logical or string specifying if and how column names of
\code{x} should be printed, possibly abbreviated.  The default is
taken from \code{\LinkA{options}{options}("sparse.colnames")} if that is set, otherwise
\code{FALSE} unless there are less than ten columns.  When
\code{TRUE} the full column names are printed.\\
When \code{col.names} is a string beginning with \code{"abb"} or
\code{"sub"} and ending with an integer \code{n} (i.e., of the form
\code{"abb... <n>"}),
the column names are \code{\LinkA{abbreviate}{abbreviate}()}d or
\code{\LinkA{substring}{substring}()}ed to (target) length \code{n}, see the examples.

\item[\code{note.dropping.colnames}] logical specifying, when
\code{col.names} is \code{FALSE} if the dropping of the column names
should be noted, \code{TRUE} by default.
\item[\code{col.trailer}] a string to be appended to the right of each
column; this is typically made use of by \code{\LinkA{show}{show}(<sparseMatrix>)}
only, when suppressing columns.
\item[\code{suppRows, suppCols}] logicals or \code{NULL}, for
\code{printSpMatrix2()} specifying if rows or columns should be
suppressed in printing.  If \code{NULL}, sensible defaults are
determined from \code{\LinkA{dim}{dim}(x)} and
\code{\LinkA{options}{options}(c("width", "max.print"))}.
Setting both to \code{FALSE} may be a very bad idea.
\item[\code{align}] a string specifying how the \code{zero.print} codes
should be aligned, i.e., padded as strings.  The default,
\code{"fancy"}, takes some effort to align the typical
\code{zero.print = "."} with the decimal points of the numbers
printed,  whereas \code{align = "right"} just makes use of
\code{\LinkA{print}{print}(*, right = TRUE)}.

\end{ldescription}
\end{Arguments}
\begin{Value}
returns \code{x} \emph{invisibly}, see \code{\LinkA{invisible}{invisible}}.
\end{Value}
\begin{Author}\relax
Martin Maechler
\end{Author}
\begin{SeeAlso}\relax
the virtual class \code{\LinkA{sparseMatrix}{sparseMatrix.Rdash.class}} and the
classes extending it;  maybe \code{\LinkA{spMatrix}{spMatrix}} as a simple
constructor of such matrices.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
f1 <- gl(5, 3, labels = LETTERS[1:5])
X <- as(f1, "sparseMatrix")
X ## <==>  show(X)  <==>  print(X)
t(X) ## shows column names, since only 5 columns

X2 <- as(gl(12, 3, labels = paste(LETTERS[1:12],"c",sep=".")),
         "sparseMatrix")
X2
## less nice, but possible:
print(X2, col.names = TRUE) # use [,1] [,2] .. => does not fit

t(X2) # suppressing column names
print(t(X2), col.names=TRUE)
print(t(X2), zero.print = "", col.names="abbr. 1")
print(t(X2), zero.print = "-", col.names="substring 2")


\end{ExampleCode}
\end{Examples}

