| 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 theconnection.For an input this is anR character vector object, and for an outputconnection the name for theR character vector to receive theoutput, 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. Howmarked strings in |
con | an output text connection. |
Details
An input text connection is opened and the character vector is copiedat time the connection object is created, andclose destroysthe copy.object should be the name of a character vector:however, short expressions will be accepted provided theydeparse toless than 60 bytes.
An output text connection is opened and creates anR character vectorof the given name in the user's workspace or in the calling environment,depending on the value of thelocal argument. This object will at alltimes hold the completed lines of output to the connection, andisIncomplete will indicate if there is an incompletefinal line. Closing the connection will output the final line,complete or not. (A line is complete once it has been terminated byend-of-line, represented by"\n" inR.) The output charactervector has locked bindings (seelockBinding) untilclose is called on the connection. The character vector canalso be retrievedviatextConnectionValue, which is theonly way to do so ifobject = NULL. If the current locale isdetected as Latin-1 or UTF-8, non-ASCII elements of the character vectorwill be marked accordingly (seeEncoding).
Opening a text connection withmode = "a" will attempt toappend to an existing character vector with the given name in theuser's workspace or the calling environment. If none is found (evenif an object exists of the right name but the wrong type) a newcharacter vector will be created, with a warning.
You cannotseek on a text connection, andseek willalways return zero as the position.
Text connections have slightly unusual semantics: they are alwaysopen, and throwing away an input text connection without closing it(so it get garbage-collected) does not give a warning.
Value
FortextConnection, a connection object of class"textConnection" which inherits from class"connection".
FortextConnectionValue, a character vector.
Note
As output text connections keep the character vector up to dateline-by-line, they are relatively expensive to use, and it is oftenbetter to use an anonymousfile() connection to collectoutput.
On (rare) platforms wherevsnprintf does not return the neededlength of output there is a 100,000 character limit on the length ofline for output connections: longer lines will be truncated with awarning.
References
Chambers JM (1998).Programming with Data.Springer, New York.ISBN 978-0-387-98503-9.
[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")