writeChar
Transfer Character Strings To and From Connections

### Description

Reads and writes known-length character data from and to a connection. The strings do not have to be null-terminated, but their lengths must be given.

### Usage

    readChar(con, nchars, useBytes = FALSE)
    writeChar(object, con, nchars = nchar(object, type = "chars"),
        eos = "", useBytes = FALSE)

### Arguments

object | a character vector containing the data to write.
con | a connection object or a character string (read as a file name). If the connection is open, it should be open in binary mode and open for reading or writing, as appropriate. If it is not yet open, it is opened in binary mode; after the data is processed, it is closed.
nchars | the lengths of the character strings. For readChar, this is the number of bytes in the file to read for each string. For writeChar, this is the number of bytes to write (not including the eos string). writeChar pads a string with null bytes if it is shorter than its corresponding nchars value.
eos | A string to be written after each string in object. The trailing null byte is also written. Use eos=NULL to mean not to write anything after each string.
useBytes | For readChar, if useBytes is TRUE, the bytes in the text strings are read as sequences of single-byte characters in the latin1 (ISO-8859-1) encoding. If FALSE (the default), these strings are interpreted as sequences of Unicode characters in the UTF-8 encoding, some of which may be encoded as multiple bytes. For writeChar, useBytes controls the writing of both object and eos. If useBytes is TRUE, writeChar writes the bytes in the text strings as produced by charToRaw. If useBytes is FALSE (the default), the text strings are written as as sequences of Unicode characters in the UTF-8 encoding. In addition, if any element of object or eos is a string with encoding "bytes", this string is written as if useBytes was TRUE.

Value

readChar | returns the strings read.
writeChar | nothing

Differences between Spotfire Enterprise Runtime for R and Open-source R

- In R, if readChar is called with useBytes=FALSE, the characters are interpreted according to the "current encoding". In Spotfire Enterprise Runtime for R, readChar with useBytes=FALSE always inteprets input characters using the UTF-8 encoding.
- In R, readChar with useBytes=FALSE reads all UTF-8 byte sequences with two to five bytes. In Spotfire Enterprise Runtime for R, reading a three-byte UTF-8 sequence encoding a character greater than 0x10FFFF or trying to read a four or five-byte UTF-8 sequence generates an error, because these are not valid Unicode characters.
- In R, if writeChar is called with useBytes=FALSE, it writes characters according to the "current encoding". In Spotfire Enterprise Runtime for R, writeChar with useBytes=FALSE always writes characters using the UTF-8 encoding (except for strings with the "bytes" encoding).

SNext S-PLUS R Diff
[cawang, 2011-06-09]: In S-PLUS, when object is a character string, nchars could be a vector or matrix.
See Also
readBin and writeBin read and write null-terminated strings. charToRaw.
Examples

    con <- tempfile()
    writeChar("123", con, 3)
    readChar(con, 3)
     # returns "123"
    writeChar( c("abc", "def"), con, c(3, 3))
    readChar(con, c(4, 4))
     # returns "abc" "def"
     # must specify nchars=c(4,4) to read terminating 0 bytes
    writeChar("123", con, 5)
     # produces warning message:
     #    more characters requested than are in the string - will zero-pad
    readChar(con, 3)
     # returns "123"
    writeChar(c("abc","def"), con, c(3,3), eos=NULL)
     # write strings without ending 0 bytes
    readChar(con, 6)
     # returns "abcdef"

Package base version 6.1.5-18
Package Index