\HeaderA{cat}{Concatenate and Print}{cat}
\keyword{print}{cat}
\keyword{file}{cat}
\keyword{connection}{cat}
\begin{Description}\relax
Outputs the objects, concatenating the representations.  \code{cat}
performs much less conversion than \code{\LinkA{print}{print}}.
\end{Description}
\begin{Usage}
\begin{verbatim}
cat(... , file = "", sep = " ", fill = FALSE, labels = NULL,
    append = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{...}] \R{} objects (see \sQuote{Details} for the types of objects allowed).
\item[\code{file}] A connection, or a character string naming the file
to print to.  If \code{""} (the default), \code{cat} prints to the
standard output connection, the console unless redirected by
\code{\LinkA{sink}{sink}}.
If it is \code{"|cmd"}, the output is piped to the command given
by \file{cmd}, by opening a pipe connection.

\item[\code{sep}] a character vector of strings to append after each element.
\item[\code{fill}] a logical or (positive) numeric controlling how the output is
broken into successive lines.  If \code{FALSE} (default), only newlines
created explicitly by \samp{"\bsl{}n"} are printed.  Otherwise, the
output is broken into lines with print width equal to the option
\code{width} if \code{fill} is \code{TRUE}, or the value of
\code{fill} if this is numeric.  Non-positive \code{fill} values are
ignored, with a warning.
\item[\code{labels}] character vector of labels for the lines printed.
Ignored if \code{fill} is \code{FALSE}.
\item[\code{append}] logical. Only used if the argument \code{file} is the
name of file (and not a connection or \code{"|cmd"}).
If \code{TRUE} output will be appended to
\code{file}; otherwise, it will overwrite the contents of
\code{file}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{cat} is useful for producing output in user-defined functions.
It converts its arguments to character vectors, concatenates
them to a single character vector, appends the given \code{sep=}
string(s) to each element and then outputs them.

No linefeeds are output unless explicitly requested by \samp{"\bsl{}n"}
or if generated by filling (if argument \code{fill} is \code{TRUE} or
numeric.)

If \code{file} is a connection and open for writing it is written from
its current position.  If it is not open, it is opened for the
duration of the call in \code{"wt"} mode and then closed again.

Currently only atomic vectors (and so not lists) and \LinkA{name}{name}s
are handled.  Character strings are output \sQuote{as is} (unlike
\code{\LinkA{print.default}{print.default}} which escapes non-printable characters and
backslash --- use \code{\LinkA{encodeString}{encodeString}} if you want to output
encoded strings using \code{cat}).  Other types of \R{} object should be
converted (e.g. by \code{\LinkA{as.character}{as.character}} or \code{\LinkA{format}{format}})
before being passed to \code{cat}.

\code{cat} converts numeric/complex elements in the same way as
\code{print} (and not in the same way as \code{\LinkA{as.character}{as.character}}
which is used by the S equivalent), so \code{\LinkA{options}{options}}
\code{"digits"} and \code{"scipen"} are relevant.  However, it uses
the minimum field width necessary for each element, rather than the
same field width for all elements.
\end{Details}
\begin{Value}
None (invisible \code{NULL}).
\end{Value}
\begin{Note}\relax
Despite its name and earlier documentation, \code{sep} is a vector of
terminators rather than separators, being output after every vector
element (including the last).  Entries are recycled as needed.
\end{Note}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{print}{print}}, \code{\LinkA{format}{format}}, and \code{\LinkA{paste}{paste}}
which concatenates into a string.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
iter <- stats::rpois(1, lambda=10)
## print an informative message
cat("iteration = ", iter <- iter + 1, "\n")

## 'fill' and label lines:
cat(paste(letters, 100* 1:26), fill = TRUE,
    labels = paste("{",1:10,"}:",sep=""))
\end{ExampleCode}
\end{Examples}

