Class

TextOutputStream

Description

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 Open shared methods.

Properties

Name	Type	Read-Only	Shared
Delimiter	String
Encoding	TextEncoding

Methods

Name	Parameters	Returns	Shared
Close
Constructor	handle As Ptr, type As IOStreamHandleTypes
Create	file As FolderItem	TextOutputStream	✓
Flush
Handle	type As IOStreamHandleTypes	Ptr
Open	file As FolderItem	TextOutputStream	✓
Write	Line As String = ""
WriteLine	Line As String = ""

Property descriptions

TextOutputStream.Delimiter

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 = EndOfLine.LF ' linefeed

TextOutputStream.Encoding

Encoding As TextEncoding

The text encoding to be used when writing data via this output stream.

Method descriptions

TextOutputStream.Close

Close

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

TextOutputStream.Constructor

Constructor(handle As Ptr, type As IOStreamHandleTypes)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a TextOutputStream instance.

Important

This method is not supported for Android.

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.

TextOutputStream.Create

Create(file 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

TextOutputStream.Flush

Flush

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

TextOutputStream.Handle

Handle(type As IOStreamHandleTypes) As Ptr

Handle returns a handle of the Type passed or -1 if the requested Type cannot be retrieved.

Important

This method is not supported for Android.

See IOStreamHandleTypes for all available types.

TextOutputStream.Open

Open(file 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.

This example adds the text in TextField1 to the text file that was opened by FolderItem:

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

TextOutputStream.Write

Write(Line As String = "")

Writes the passed data Line 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

TextOutputStream.WriteLine

WriteLine(Line As String = "")

Writes the data Line 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

Interfaces

The TextOutputStream class implements the Writeable class interface.

Notes

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.

This code appends the text in TextField1 to the text file that was opened by FolderItem:

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

Sample code

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

Compatibility

All project types on all supported operating systems.