Binary Files
From Xojo Documentation
Binary files are simply files that store values in their binary format rather than as text. For example, the number 30000 stored as text requires 5 characters of text to store in a text file, which can be 5 or more bytes depending on the encoding. In a binary file, this number can be written as a short integer (or just “short”), which requires only 2 bytes.
Binary files also have the added benefit that you can read and write to a file without having to close the file in-between, as is required with text files. For example, you can open a binary file, read some data, then write some data, and close it. You can also read and write anywhere in the file without having to read through all the data preceding the data you want.
Although text-based file formats are increasingly common, many apps also store data in a binary format. The format is simply the arrangement of data within the file. In order to read a binary file, you must know how the data is arranged. If your own app created the file, you will know this, but if the file was created by an app you didn't write, you may not know it. Some formats are made public. For example, the PNG format is public. Other formats are not. Many software vendors do not publish the binary formats that their apps use to create documents.
Binary Streams
Data read from or written to a binary file is accessed using the BinaryStream class. This class represents the flow of binary data between the FolderItem and the file it represents. Unlike the TextInputStream class (which can only be used to read from a text file) and the TextOutputStream class (which can only be used to write data to a text file), the BinaryStream class can be used for both reading data and writing data. You can even indicate to the BinaryStream that you will only be reading data from the file so that the file can continue to be available to other apps for reading or writing.
You can use a BinaryStream to read and write specific types of data, such as strings, short integers, long integers, currency, and single bytes. They can also be used to read and write raw unformatted binary data as a block of bytes.
With iOS projects you should use the Xojo.IO.BinaryStream class. Refer to UserGuide:iOS Files for information on using binary files in iOS projects.
Reading from a Binary File
Once you have a FolderItem that represents the file you wish to open, you open the file using the Open method of the BinaryStream class. It returns a BinaryStream object which you then use to read data from the stream. The BinaryStream class includes separate methods for reading each of the built-in data types.
iOS projects use the Xojo.IO.BinaryStream class, which works similarly.
The BinaryStream keeps track of the last position in the file you read from in its Position property. However, you can change this property's value to move the position to any location in the file.
This desktop code displays the Open File Selector, reads a file made up of strings, and displays those strings in a TextArea. Notice that since the code is only reading data and not writing, False is passed to the Open method to indicate the file should be opened in “read-only” mode. Also, reading continues in a loop until the stream's EOF (end of file) property is True. The EOF property is automatically set to True once the end of the file is reached.
Dim stream As BinaryStream
f = GetOpenFolderItem(FileTypes1.Text)
If f <> Nil Then
stream = BinaryStream.Open(f, False)
Do
TextArea1.AppendText(stream.Read(255))
Loop Until stream.EOF
stream.Close
End If
When you read a binary file that contains text, you need to take the encoding of the characters into account. To do so, you can pass an optional parameter to the Read method that specifies the encoding. Use the Encodings module to get any encoding and pass it to Read. For example, the following code specifies the UTF8 encoding:
Writing to a Binary File
Once you have a FolderItem that represents the file you wish to open and write to, you can open the file using the Open method of the BinaryStream class. If you are creating a new file, use the Create method of the BinaryStream class. This method returns a BinaryStream. You then use the appropriate method for writing data to the stream. The BinaryStream class includes separate methods for each of the built-in data types.
The BinaryStream keeps track of the last position in the file you wrote to in its Position property. However, you can change this property’s value to move the position to any location in the file.
When you are finished writing data to the file, call the BinaryStream's Close method to close the stream to the file making the file available to be opened again.
This desktop code displays the Save As dialog box and writes the contents of the TextArea1 to a text file:
Dim stream As BinaryStream
f = GetSaveFolderItem(FileTypes1.Text, "Untitled.txt")
If f <> Nil Then
stream = BinaryStream.Create(f, True)
stream.Write(TextArea1.Text)
stream.Close
End If
You can also append data to the end of a binary file if you open it in read/write mode. This code is a modified version of the code in the "Reading from a Binary File" section above. It opens the file in read/write mode (by specifying True for the 2nd parameter) and then after the EOF is reached, it writes some additional data (in this case text) to the end.
Dim stream As BinaryStream
f = GetOpenFolderItem("")
If f <> Nil Then
stream = BinaryStream.Open(f, True)
Do
TextArea1.AppendText(stream.Read(255))
Loop Until stream.EOF
stream.Write(EndOfLine + "This text is appended to the end of the file.")
stream.Close
End If
See Also
BinaryStream, FolderItem classes; UserGuide:Framework, UserGuide:Text Files topics