君WRITE Write data to a native file


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

          DATA 君WRITE 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) 君WRITE 100 2
 DOMAIN ERROR
      (1.0 1.5 2.0) 君WRITE 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.


Topic: APLX Help : Help on APL language : System Functions & Variables : 君WRITE Write data to native file
[ Previous | Next | Contents | Index ]