textConnection {base} | R Documentation

## Text Connections

### Description

Input and output text connections.

### Usage

    textConnection(object, open = "r", local = FALSE,
                   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 `NULL` (for none).
`open` | character string. Either `"r"` (or equivalently `""`) for an input connection or `"w"` or `"a"` for an output connection.
`local` | logical. Used only for output connections. If `TRUE`, output is assigned to a variable in the calling environment. Otherwise the global environment is used.
`encoding` | character string, partially matched. Used only for input connections. How marked strings in `object` should be handled: converted to the current locale, used byte-by-byte or translated to UTF-8.
`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")

[Package base version 3.3.2 Index]