This is documentation for Mathematica 5, which was
based on an earlier version of the Wolfram Language.
View current documentation (Version 11.1)

Documentation / Mathematica / Add-ons & Links / Standard Packages / Utilities /

Utilities`BinaryFiles`

This package provides special functions for opening, reading from, and writing to a binary data file. The standard Mathematica functions can be used for this purpose, but the functions provided by this package automatically set the relevant options to values suited to binary files. For example, the functions provided for opening a binary file use the option PageWidth -> Infinity for setting the output format. Mathematica also provides experimental functionality that may be much more efficient at handling binary files than this package, in the functions Experimental`BinaryImport and Experimental`BinaryExport.

Operations involving binary files.

The open file functions return the appropriate InputStream or OutputStream object. As with the corresponding built-in functions OpenWrite and OpenAppend, if the file exists, OpenWriteBinary overwrites the file, while OpenAppendBinary appends to the end of the file. If one of the read or write functions is used on a filename, rather than an opened stream, a stream to that file is opened and left at the position current at the end of the operation. Streams opened for binary operations can be closed using the built-in function Close.

The binary read functions ReadBinary and ReadListBinary behave much as their standard counterparts, Read and ReadList. The primary difference is that the second argument is held until after the read has occurred. This is important when the second argument is an expression involving binary types. In this case, the types are filled in the order of evaluation.

WriteBinary uses a conversion function to convert data into a binary form. This binary form is a list of bytes, each byte represented as an integer between 0 and 255. The conversion function is specified by the ByteConversion option, which has a default of ToBytes. The list generated by the conversion function is flattened out and written as a stream of bytes.

This loads the package.

In[1]:= << Utilities`BinaryFiles`

Here is a list of sample data.

In[2]:= data = N[Table[10^n, {n, -10, 10}]]

Out[2]=

This opens an output stream to the file binarytest.

In[3]:= stream = OpenWriteBinary["binarytest"]

Out[3]=

The list data is written to the file in the default format.

In[4]:= WriteBinary[stream, data]

This closes the stream.

In[5]:= Close[stream]

Out[5]=

This reads in the file binarytest as a list of bytes, giving the binary format of this sequence of numbers.

In[6]:= ReadListBinary["binarytest", Byte]

Out[6]=

Note that you can retrieve the original data by reading the file in the same format that it was written.

In[7]:= ReadListBinary["binarytest", Double]

Out[7]=

Types of binary objects that can be read.

The types of binary objects listed represent the types that can be read and converted. The floating-point formats Single and Double follow the IEEE specification, used by most C libraries. Once in Mathematica, both of these formats are classified as machine precision.

Here the data in binarytest is treated as integers and read in the first five.

In[8]:= ReadListBinary["binarytest", SignedInt16, 5]

Out[8]=

Unlike Read and ReadList, ReadBinary and ReadListBinary do not evaluate their second argument until after the read has occurred.

In[9]:= ReadListBinary["binarytest", Double + Double]

Out[9]=

Option for ReadBinary and ReadListBinary.

The format in which integers are read is controlled by the ByteOrder option. Integers can be treated as least significant byte first or little-endian (a format most often found on machines based on e.g. Intel x86 processors or DEC/HP Alpha) instead of the default most significant byte first or big-endian (a format found on Motorola-based machines such as the Power Mac or on machines based on the Sun UltraSPARC). This option is also available when converting to binary form using ToBytes.

Utility to convert to byte form.

The ToBytes function converts some kinds of expressions to their byte form (i.e., a list of integers between 0 and 255). ToBytes also works across nested lists of objects of type Integer, Real, or String, converting them to the byte form of one of the binary types listed above. An Integer object is converted to the byte form of the binary type given by the option IntegerConvert. The same may be said for Real objects and the option RealConvert and String objects and the option StringConvert. However, if a type is explicitly specified as a second argument to ToBytes, then conversion is made to that type, overriding any options.

This gives the byte form of the real number -34.3421435.

In[10]:= ToBytes[-34.3421435]

Out[10]=

This converts -34.3421435 to a string of digits. A warning message is issued.

In[11]:= ToBytes[-34.3421435, CString]

Out[11]=

Options for ToBytes.

The ToBytes options control how ToBytes performs type conversion. All of the binary types can be used here. Note that negative integers written as integers (e.g., Int8) will always be automatically written as signed numbers, even if the conversion type does not explicitly specify signed numbers (e.g., SignedInt8).

When using WriteBinary, it may be advantageous to use a conversion function other than ToBytes, for example when writing symbolic expressions in a binary format. If your data are already in byte form, ByteConversion -> Identity tells WriteBinary to perform no conversion.

This opens an output stream to the file binarytest2.

In[12]:= stream = OpenWriteBinary["binarytest2"]

Out[12]=

The data are written to the file in single precision real format.

In[13]:= WriteBinary[stream, data,
ByteConversion ->
(ToBytes[#, RealConvert -> Single]&)]

This closes the stream.

In[14]:= Close[stream]

Out[14]=

Reading the file assuming a double precision real format yields nonsense.

In[15]:= ReadListBinary["binarytest2", Double]

Out[15]=

Of course, the file can be read using the format in which it was written, single precision real format.

In[16]:= ReadListBinary["binarytest2", Single]

Out[16]=