In order to write text to a file, you need to create a TextOutputStream object. TextOutputStreams have methods that allow to write to a file and close the file when you are done writing to it. They are created by calling the Create and Append shared methods.
f As FolderItem
type As IOStreamHandleTypes
f As FolderItem
Data As String
data As String
Delimiter As String
The character used to mark the end of a line of text written to the file. The OS default for EndOfLine is used.
This example sets the Linefeed as the delimiter.
Var t As TextOutputStream t.Delimiter = Encodings.UTF8.Chr(10) // linefeed
Encoding As TextEncoding
The text encoding to be used when writing data via this output stream.
Closes the TextOutputStream.
This example closes the TextOutputStream after the write operation is complete.
Var f As FolderItem Var t As TextOutputStream f = FolderItem.ShowOpenFileDialog(FileTypes1.Text) If f <> Nil Then t = TextOutputStream.Open(f) t.Write(TextField1.Text) t.Close End If
Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.
Creates a TextOutputStream instance.
Type is one of the IOStreamHandleTypes and Handle is the appropriate handle type specified by the Type parameter.
For instance, you can use a Declare to open a file with whatever permissions that you wish, and then pass the Handle to a stream object’s constructor.
Create(f As FolderItem) As TextOutputStream
Creates a text file for so that text can be written. The write is done by calling Write or WriteLine. Call Close when you are finished writing to the file.
This method is shared.
If the file exists, it will be erased and recreated.
An IO error will trigger an IOException.
This code writes text from a TextField into a file:
Var f As FolderItem = FolderItem.ShowSaveFileDialog(FileTypes1.Text, "Create Example.txt") If f <> Nil Then Try Var t As TextOutputStream = TextOutputStream.Create(f) t.WriteLine(TextField1.Text) t.Close Catch e As IOException // handle error End Try End If
Immediately sends the contents of internal write buffers to disk or to the output stream.
This function can be useful in point-to-point communication over sockets and similar connections: To optimize for transmission performance, some types of output streams try to collect small pieces of written data into one larger piece for sending instead of sending each piece out individually. By calling Flush, the data collection is stopped and the data is sent without further delay, reducing latency.
When using this on a stream that ends up as a file on disk, it is useful, too: Any short parts of previously written data are written to disk right away, ensuring the data is actually on disk if the application terminates abruptly, e.g. due to a crash.
Avoid calling this method too often. For example, do not call it between successive Write calls because you’ll slow down performance without getting much benefit.
A typical use case would look like this:
mySocket.Write("you typed: ") mySocket.Write(key) mySocket.Write(".") mySocket.Flush
Handle returns a handle of the Type passed or -1 if the requested Type cannot be retrieved.
See IOStreamHandleTypes for all available types.
Open(f As FolderItem) As TextOutputStream
Opens the passed file so that text can be added to the end of the file.
This method is shared.
If no file exists at the specified location, one is created. If the file cannot be created or opened for adding, an IOException is raised. Add text by calling Write or WriteLine.
Var f As FolderItem = FolderItem.ShowOpenFileDialog(FileTypes1.Text) If f <> Nil Then Try Var t As TextOutputStream = TextOutputStream.Open(f) t.Write(TextField1.Text) Catch e As IOException // handle error End Try End If
Write(Data As String)
Writes the passed data to the output stream.
Note that in order to make sure that the data actually ends up on disk or gets sent to the socket it is connected to, the stream must either get closed or the Flush method be called. Otherwise, the data, if small, may end up temporarily in a write buffer before either a certain time has passed or more data is written. This buffering increases performance when writing lots of small pieces of data, but may be causing unwanted delays when another process, e.g. the other end of a socket connection, is waiting for the data. Consider calling the Flush method to reduce latencies that this buffering may cause in such cases.
If Write fails, an IOException will be raised.
This example displays the Save As dialog box and writes the contents of the TextArea1 to a text file.
Var f As FolderItem Var stream As BinaryStream f = FolderItem.ShowSaveFileDialog(FileTypes1.Text, "Untitled.txt") If f<> Nil Then stream = BinaryStream.Create(f, True) stream.Write(TextArea1.Text) stream.Close End If
WriteLine(data As String)
Writes the data passed to the TextOutputStream and appends the Delimiter to the end of the line.
If WriteLine fails, an IOException will be raised.
This example displays the Save As dialog box. A text file is then created and the text properties of three TextFields are written to the new file. Finally the file is closed.
Var file As FolderItem = FolderItem.ShowSaveFileDialog(FileTypes1.Text, "MyInfo.txt") If file <> Nil Then Var output As TextOutputStream output = TextOutputStream.Create(file) output.WriteLine(NameField.Text) output.WriteLine(AddressField.Text) output.WriteLine(PhoneField.Text) output.Close End If
The TextOutputStream class implements the Writeable class interface.
Setting the text encoding
The default encoding is UTF8. If you want no encoding, use a BinaryStream. If you need to write a file using a different encoding, use the Encoding property before passing the text to the Write or WriteLine methods.
Var documents As FolderItem = SpecialFolder.Documents If documents <> Nil Then Var file As FolderItem = Documents.Child("Sample.txt") If file <> Nil Then Try // TextOutputStream.Create raises an IOException if it can't open the file for some reason. Var output As TextOutputStream = TextOutputStream.Create(file) output.Encoding = Encodings.WindowsANSI output.Write(TextField1.Text) output.Close Catch e As IOException // handle End Try End If End If
All available encodings are in the Encodings module.
Creating and appending to a text file
Use Open when you want to open an existing text file and add text data to it. Use Create to write to a new text file. The following two examples illustrate the difference. Each example writes the text in TextField1 to the text file.
Var file As FolderItem Var output As TextOutputStream file = FolderItem.ShowOpenFileDialog(FileTypes1.Text) If file <> Nil then output = TextOutputStream.Open(file) output.Write(TextField1.Text) output.Close End If
This code writes to a new text file.
Var output As TextOutputStream Var file As FolderItem = FolderItem.ShowSaveFileDialog("", "CreateExample.txt") If file <> Nil Then output = TextOutputStream.Create(file) output.WriteLine(TextField1.Text) output.Close End If
This code displays the Save As dialog box. A text file is then created and the text properties of three TextFields are written to the new file. Finally the file is closed.
Var file As FolderItem = FolderItem.ShowSaveFileDialog("", "MyInfo.txt") If file <> Nil Then Var fileStream As TextOutputStream fileStream = TextOutputStream.Create(file) fileStream.WriteLine(NameField.Text) fileStream.WriteLine(AddressField.Text) fileStream.WriteLine(PhoneField.Text) fileStream.Close End If
All projects types on all supported operating systems.