Write Text File

{R}←X ⎕NPUT Y

This function writes character data to a text file. See also Read Text File.

Y is either a simple character vector or scalar containing the name of the file to be written, or a 2-item vector whose first item is the file name and whose second is an integer scalar specifying flags for the operation.

If flags is 0 (the default value if omitted) the file will not be overwritten if it already exists and ⎕NPUT will signal an error. If flags is 1 the file will be overwritten. If flags is 2 the file will be appended to; i.e.

flags	file does not exist	file exists
0	data is written to new file	error signalled, file is unchanged
1	data is written to new file	file is overwritten
2	data is written to new file	data is appended to file

The left-argument X is comprised of 1, 2 or 3 items which identify (content) (encoding) (newline) respectively.

content is either a vector of character vectors, each of which represents a line in the file to be written, or a simple character vector.

If specified, encoding is either:

a character vector from the first column in the table File Encodings. If encoding specifies a UTF format, it may be qualified with -BOM (e.g. UTF-8-BOM), which causes a Byte Order Mark (BOM) to be written at the beginning of the file or -NOBOM which does not. If the -BOM or -NOBOM suffix is omitted, UTF-8 defaults to UTF-8-NOBOM, while the other UTF formats default to -BOM.
a 256-element numeric vector that maps each possible byte value (0-255) to a Unicode code point (1st element = Unicode code point corresponding to byte value 0, and so on). ¯1 indicates that the corresponding byte value is not mapped to any character. Apart from ¯1, no value may appear in the table more than once.

If omitted, encoding defaults to UTF-8-NOBOM.

Note: If a non-empty file is appended to:

No BOM will be written, even if encoding specifies it.
No check is made that the existing file content is text in the same encoding format.

If specified, newline is numeric and is either ⍬ or a scalar or vector from the column labelled Value in the newline characters section of the table Line separators:. Any other value causes DOMAIN ERROR. If newline is omitted it defaults to (13 10) on Windows and 10 on other platforms.

If content is nested, each element is considered to be to a logical line in the file, and when the file is written, a line separator character corresponding to newline is appended to each and every element, i.e. the data written to the file (excluding the BOM) is:

      ∊content,¨⊂⎕UCS newline

If content is simple each and every LF (⎕UCS 10) character that it contains is first replaced by the character corresponding to newline. If not present, one LF character is added to the end of the array prior to these replacements.

In both cases, any other line separator characters are written as is to the file. This allows the APL programmer to insert other line endings if so desired.

If content contains anything other than a character vector or scalar (or these, nested) then a DOMAIN ERROR is signalled.

The shy result R is the number of bytes written to the file.

Note that when content is a vector of character vectors and encoding is omitted; it is necessary to enclose the left argument.

Example:

      txt←'mene' 'mene' 'tekel' 'upharsin'
      ⎕←(⊂txt) ⎕NPUT 'writing.txt'
25
      ⊢(⊂'adding' '3' 'lines')⎕NPUT'writing.txt' 2
18