readbytes - reads bytes from a file or pipe as a string or list
|
Calling Sequence
|
|
readbytes(file)
readbytes(file, len)
readbytes(file, TEXT)
readbytes(file, len, TEXT)
readbytes(file, rtable)
readbytes(file, len, rtable)
|
|
Parameters
|
|
file
|
-
|
file descriptor or file name
|
len
|
-
|
number of bytes to read
|
TEXT
|
-
|
specifies that bytes are stored in a string
|
rtable
|
-
|
specifies an Array, Matrix, or Vector into which to write the bytes
|
|
|
|
|
Description
|
|
•
|
readbytes reads the specified number of bytes from the specified file.
|
•
|
If len is not specified, readbytes reads one byte unless an rtable was given, in which case readbytes reads as many bytes as needed to fill the rtable.
|
•
|
If len is specified as infinity, readbytes reads the rest of the file.
|
•
|
If less than len bytes remain in the file, fewer bytes are read.
|
•
|
If no bytes remain, readbytes returns 0 instead of a list, string, or rtable. If the file was specified as a file name, it is automatically closed at this point.
|
•
|
The return type of readbytes depends on the options specified. If TEXT was specified, a string is returned. If an rtable was specified, the rtable is returned. Otherwise, a list of integers is returned.
|
•
|
If TEXT is specified, reading stops when either a zero byte is read, or the specified number of bytes have been read. If a zero byte is read, it is discarded.
|
•
|
If an rtable is given, data is read into its data block. The rtable must have already been created with the desired size and it must have a hardware datatype; readbytes will not create it automatically. Loading into hardware rtables with integer[] and float[] datatypes is inherently architecture dependent, and guaranteed to work only if the file was written on the same architecture on which it is being read. It may work between some architectures.
|
•
|
Data is always read into an rtable according to the underlying layout of memory. Of note, when the rtable has more than one dimension, the view of the data will be column-major when the rtable has order=Fortran_order, and row-major if the rtable has order=C_order. That is, if bytes 1, 2, 3 are read into a 3x3 Matrix with datatype=integer[1] and order=Fortran_order, the result in Maple will have [1,2,3] as the first column of the Matrix. If a similar matrix is used but with order=C_order, the result will have [1,2,3] as the first row.
|
•
|
When passed an rtable, readbytes returns the rtable as the result.
|
•
|
If a file name is given, and that file is not yet open, it is opened in READ mode. The file is opened with type TEXT if TEXT was specified, or with type BINARY otherwise.
|
|
|
Thread Safety
|
|
•
|
The readbytes command is thread safe as of Maple 15.
|
•
|
Parallel calls to file i/o commands on the same file descriptor will be serialized in an arbitrary order. If you need the commands to execute in a particular order you must use Maple's synchronization tools to enforce this. See Threads:-Mutex.
|
|
|
Examples
|
|
Copy a file and return the file size.
>
|
|
Create a compressed version of a data file
>
|
|
>
|
|
>
|
|
>
|
|
>
|
|
>
|
|
|
|