[ RDocumentation ](/)

Moon  [ ](https://github.com/datacamp/rdocumentation-2.0) [ Learn R
](https://www.datacamp.com/learn/r)

Search all packages and functions

[ base  (version  3.6.2  ) ](/packages/base/versions/3.6.2)

#  textConnection: 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
](/link/connection?package=base&version=3.6.2) . 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.

##  Value

For ` textConnection ` , a connection object of class ` "textConnection" `
which inherits from class ` "connection" ` .

For ` textConnectionValue ` , a character vector.

##  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 ](/link/deparse?package=base&version=3.6.2)
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
](/link/isIncomplete?package=base&version=3.6.2) ` 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 ](/link/lockBinding?package=base&version=3.6.2)
` ) 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.

##  References

Chambers, J. M. (1998) _Programming with Data. A Guide to the S Language._
Springer. [S has input text connections only.]

##  See Also

` [ connections ](/link/connections?package=base&version=3.6.2) ` , ` [
showConnections ](/link/showConnections?package=base&version=3.6.2) ` , ` [
pushBack ](/link/pushBack?package=base&version=3.6.2) ` , ` [ capture.output
](/link/capture.output?package=base&version=3.6.2) ` .

##  Examples

[ Run this code
](https://app.datacamp.com/workspace/preview?_tag=rdocs&rdocsPath=packages%2Fbase%2Fve