⎕NWRITE Write data to a native file

⎕NWRITE is used to write data to a tied file. The file must have been opened in a mode that permits writing. The syntax of ⎕NWRITE is similar to ⎕NREAD ({} means optional) :

          DATA ⎕NWRITE TIENO {,CONV {,STARTBYTE}}

TIENO specifies the file to write to

CONV specifies any conversion to apply to the data before writing it; default is no conversion (see below)

STARTBYTE specifies the offset from the start of the file at which to begin writing. A value of ¯1 (default) specifies the current file position. A value of ¯2 specifies that the data should be appended to end of file.

The DATA may be of any simple data type; nested and mixed arrays are not permitted. The data may be of any shape or rank but will be ravelled before writing to file.

The conversion mode parameter allows the user to specify a conversion to apply to the data before writing it to the file. It may be used to coerce data to a desired data type before writing. For example an array of booleans can be converted to integers before writing to file. A full list of possible values for CONV is as follows :

   Normal modes:

   0      write data unconverted
   1      write data as booleans, 1 bit per element
   2      write data as 32-bit integers
   3      write data as 64-bit IEEE double-precision floating point numbers
   4      write  character  data,   translating  from  APLX's  own  internal
          representation to external format.
   5      write  character  data,   translating  from  APLX's  own  internal
          representation to Unicode UTF-16 (2 bytes per element).
   6      write data as 32-bit IEEE single-precision floating point numbers
   8      write  character  data,   translating  from  APLX's  own  internal
          representation to Unicode UTF-8 (variable bytes per element).

   Byte-swapped modes:

  ¯2      write data as 32-bit byte-swapped integers
  ¯3      write data as 64-bit byte-swapped floats
  ¯5      write data as byte-swapped Unicode characters
  ¯6      write data as 32-bit byte-swapped floats

For compatibility with some other APL interpreters the following conversion specifiers are also supported:

   11      write data as booleans (same as mode=1)
   82      write data as raw characters (same as mode=0)
  163      write data as 16-bit integers.
  323      write data as 32-bit integers (same as mode=2)
  325      write data as 32-bit floating point numbers (same as mode=6)
  645      write data as 64-bit floating point numbers (same as mode=3)
 ¯163      write data as 16-bit integers with byte-swapping
 ¯323      write data as 32-bit integers with byte-swapping (same as mode=¯2) 
 ¯325      write data as 32-bit floats with byte-swapping (same as mode=¯6)
 ¯645      write data as 64-bit floats with byte-swapping (same as mode=¯3)

Under APLX64, the following additional conversion types are available:

    7      write data as 64-bit integers
   ¯7      write data as 64-bit integers with byte-swapping
  643      write data as 64-bit integers (same as mode=7)
 ¯643      write data as 64-bit integers with byte-swapping (same as mode=¯7)

An inappropriate combination of source data type and conversion mode will lead to a DOMAIN ERROR. For example an attempt to convert the following floating point vector to integers will fail :

     (1.0 1.5 2.0) ⎕NWRITE 100 2
 DOMAIN ERROR
      (1.0 1.5 2.0) ⎕NWRITE 100 2
      ^

In the event of an illegal conversion, no data is written to disc and the current file position is unchanged.

When writing booleans, note that the number of elements to write is padded with zeros to give a whole number of bytes before writing to file.