| textConnection {base} | R Documentation |
Text Connections
Description
Input and output text connections.
Usage
textConnection(object, open = "r", local = FALSE,
name = deparse1(substitute(object)),
encoding = c("", "bytes", "UTF-8"))
textConnectionValue(con)
Arguments
object |
character. A description of the connection.
For an input this is an R character vector object, and for an output
connection the name for the R character vector to receive the
output, or |
open |
character string. Either |
local |
logical. Used only for output connections. If |
name |
a |
encoding |
character string, partially matched. Used only for input connections. How
marked strings in |
con |
an output text connection. |
Details
An input text connection is opened and the character vector is copied
at time the connection object is created, and close destroys
the copy. object should be the name of a character vector:
however, short expressions will be accepted provided they deparse to
less than 60 bytes.
An output text connection is opened and creates an R character vector
of the given name in the user's workspace or in the calling environment,
depending on the value of the local argument. This object will at all
times hold the completed lines of output to the connection, and
isIncomplete will indicate if there is an incomplete
final line. Closing the connection will output the final line,
complete or not. (A line is complete once it has been terminated by
end-of-line, represented by "\n" in R.) The output character
vector has locked bindings (see lockBinding) until
close is called on the connection. The character vector can
also be retrieved via textConnectionValue, which is the
only way to do so if object = NULL. If the current locale is
detected as Latin-1 or UTF-8, non-ASCII elements of the character vector
will be marked accordingly (see Encoding).
Opening a text connection with mode = "a" will attempt to
append to an existing character vector with the given name in the
user's workspace or the calling environment. If none is found (even
if an object exists of the right name but the wrong type) a new
character vector will be created, with a warning.
You cannot seek on a text connection, and seek will
always return zero as the position.
Text connections have slightly unusual semantics: they are always open, and throwing away an input text connection without closing it (so it get garbage-collected) does not give a warning.
Value
For textConnection, a connection object of class
"textConnection" which inherits from class "connection".
For textConnectionValue, a character vector.
Note
As output text connections keep the character vector up to date
line-by-line, they are relatively expensive to use, and it is often
better to use an anonymous file() connection to collect
output.
On (rare) platforms where vsnprintf does not return the needed
length of output there is a 100,000 character limit on the length of
line for output connections: longer lines will be truncated with a
warning.
References
Chambers, J. M. (1998)
Programming with Data. A Guide to the S Language. Springer.
[S has input text connections only.]
See Also
connections, showConnections,
pushBack, capture.output.
Examples
zz <- textConnection(LETTERS)
readLines(zz, 2)
scan(zz, "", 4)
pushBack(c("aa", "bb"), zz)
scan(zz, "", 4)
close(zz)
zz <- textConnection("foo", "w")
writeLines(c("testit1", "testit2"), zz)
cat("testit3 ", file = zz)
isIncomplete(zz)
cat("testit4\n", file = zz)
isIncomplete(zz)
close(zz)
foo
# capture R output: use part of example from help(lm)
zz <- textConnection("foo", "w")
ctl <- c(4.17, 5.58, 5.18, 6.11, 4.5, 4.61, 5.17, 4.53, 5.33, 5.14)
trt <- c(4.81, 4.17, 4.41, 3.59, 5.87, 3.83, 6.03, 4.89, 4.32, 4.69)
group <- gl(2, 10, 20, labels = c("Ctl", "Trt"))
weight <- c(ctl, trt)
sink(zz)
anova(lm.D9 <- lm(weight ~ group))
cat("\nSummary of Residuals:\n\n")
summary(resid(lm.D9))
sink()
close(zz)
cat(foo, sep = "\n")