This function writes character data to a 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.
In all cases, newline is appended if required to a simple vector or to each vector in a vector of vectors.
If content contains anything other than a character vector or scalar (or these, nested) then a DOMAIN ERROR is signalled.
If both encoding and newline are omitted X specifies only content and may be a simple character vector or a vector of character vectors.
The shy result R is the number of bytes written to the file.
Examples:
txt←'mene' 'mene' 'tekel' 'upharsin'
⎕←(⊂txt) ⎕NPUT 'writing.txt'
25
⊢(⊂'adding' '3' 'lines')⎕NPUT'writing.txt' 2
18LF←⎕UCS 10
t←'adding',LF,'3',LF,'lines',LF
⊢t ⎕NPUT'writing.txt' 2
18
NEOL Option
The NEOL variant option specifies how embedded line separators are treated.
| 0 | embedded line separator characters are preserved as is |
| 1 | every embedded LF is replaced by newline |
| 2 | every embedded line separator character is replaced by newline |
Embedded line-separator examples
LF CR←⎕UCS 10 13
t←'adding',LF,'3',CR,'lines',CR,LF
⊢t ⎕NPUT'writing.txt' 2
17
⊢t(⎕NPUT⍠'NEOL' 0)'writing.txt' 2
16
⊢t(⎕NPUT⍠'NEOL' 2)'writing.txt' 2
18
t contains three lines each with different line endings: LF, CR and CRLF.
In the first example (NEOL is by default 1), only the LF is normalised so the written file contains lines ending with CRLF, CR and CRLF.
In the second example, none of the line endings are normalised so the written file contains lines ending with LF, CR and CRLF.
In the third example, all of the line endings are normalised so the written file contains lines ending with CRLF, CRLF and CRLF.