Class

# TextOutputStream

<div class="rst-class">

forsearch

</div>

Stream

<div class="rst-class">

forsearch

</div>

Textfile

<div class="rst-class">

forsearch

</div>

File

<div class="rst-class">

forsearch

</div>

Files

<div class="rst-class">

forsearch

</div>

Writing

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

In order to write text to a file, you need to create a <span class="title-ref">TextOutputStream</span> object. <span class="title-ref">TextOutputStreams</span> 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

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                    | Type                                                 | Read-Only | Shared |
|-----------------------------------------|------------------------------------------------------|-----------|--------|
| `Delimiter<textoutputstream.delimiter>` | `String</api/data_types/string>`                     |           |        |
| `Encoding<textoutputstream.encoding>`   | `TextEncoding</api/text/encoding_text/textencoding>` |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                         | Parameters                                                                                                        | Returns                                         | Shared |
|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|--------|
| `Close<textoutputstream.close>`              |                                                                                                                   |                                                 |        |
| `Constructor<textoutputstream.constructor0>` | handle As `Ptr</api/data_types/additional_types/ptr>`, type As `IOStreamHandleTypes<runtime.iostreamhandletypes>` |                                                 |        |
| `Create<textoutputstream.create>`            | file As `FolderItem</api/files/folderitem>`                                                                       | <span class="title-ref">TextOutputStream</span> | ✓      |
| `Flush<textoutputstream.flush>`              |                                                                                                                   |                                                 |        |
| `Handle<textoutputstream.handle_method>`     | type As `IOStreamHandleTypes<runtime.iostreamhandletypes>`                                                        | `Ptr</api/data_types/additional_types/ptr>`     |        |
| `Open<textoutputstream.open>`                | file As `FolderItem</api/files/folderitem>`                                                                       | <span class="title-ref">TextOutputStream</span> | ✓      |
| `Write<textoutputstream.write>`              | Line As `String</api/data_types/string>` = ""                                                                     |                                                 |        |
| `WriteLine<textoutputstream.writeline>`      | Line As `String</api/data_types/string>` = ""                                                                     |                                                 |        |

## Property descriptions

<div id="textoutputstream.delimiter">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

TextOutputStream.Delimiter

**Delimiter** As `String</api/data_types/string>`

> The character used to mark the end of a line of text written to the file. The OS default for `EndOfLine</api/text/endofline>` is used.
>
> This example sets the Linefeed as the delimiter.
>
> ``` xojo
> Var t As TextOutputStream
> t.Delimiter = EndOfLine.LF ' linefeed
> ```

<div id="textoutputstream.encoding">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

TextOutputStream.Encoding

**Encoding** As `TextEncoding</api/text/encoding_text/textencoding>`

> The text encoding to be used when writing data via this output stream.
>
> This example sets the encoding for a file:
>
> ``` xojo
> Var f As FolderItem = SpecialFolder.Documents.Child("test.txt")
> Var t As TextOutputStream = TextOutputStream.Create(f)
>
> t.Encoding = Encodings.UTF8
> t.WriteLine(TextField1.Text)
> t.Close
> ```

## Method descriptions

<div id="textoutputstream.close">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

TextOutputStream.Close

**Close**

> Closes the <span class="title-ref">TextOutputStream</span>.
>
> This example closes the <span class="title-ref">TextOutputStream</span> after the write operation is complete.
>
> ``` xojo
> 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
> ```

<div id="textoutputstream.constructor0">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

TextOutputStream.Constructor

**Constructor**(handle As `Ptr</api/data_types/additional_types/ptr>`, type As `IOStreamHandleTypes<runtime.iostreamhandletypes>`)

> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> `Constructors</api/language/constructor>` are special methods called when you create an object with the `New</api/language/new>` keyword and pass in the parameters above.
>
> </div>
>
> Creates a <span class="title-ref">TextOutputStream</span> instance.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> This method is not supported for Android.
>
> </div>
>
> *type* is one of the `IOStreamHandleTypes<runtime.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.

<div id="textoutputstream.create">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

TextOutputStream.Create

**Create**(file As `FolderItem</api/files/folderitem>`) As <span class="title-ref">TextOutputStream</span>

> 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</api/language/shared>`.
>
> If the file exists, it will be erased and recreated.
>
> An IO error will trigger an `IOException</api/exceptions/ioexception>`.
>
> This code writes text from a TextField into a file:
>
> ``` xojo
> 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
> ```

<div id="textoutputstream.flush">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

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:
>
> ``` xojo
> mySocket.Write("you typed: ")
> mySocket.Write(key)
> mySocket.Write(".")
> mySocket.Flush
> ```

<div id="textoutputstream.handle_method">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

TextOutputStream.Handle

**Handle**(type As `IOStreamHandleTypes<runtime.iostreamhandletypes>`) As `Ptr</api/data_types/additional_types/ptr>`

> Handle returns a handle of the *type* passed or -1 if the requested *type* cannot be retrieved.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> This method is not supported for Android.
>
> </div>
>
> See `IOStreamHandleTypes<runtime.iostreamhandletypes>` for all available types.

<div id="textoutputstream.open">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

TextOutputStream.Open

**Open**(file As `FolderItem</api/files/folderitem>`) As <span class="title-ref">TextOutputStream</span>

> Opens the passed *file* so that text can be added to the end of the file.
>
> This method is `shared</api/language/shared>`.
>
> If no *file* exists at the specified location, one is created. If the file cannot be created or opened for adding, an `IOException</api/exceptions/ioexception>` is raised. Add text by calling Write or WriteLine.
>
> This example adds the text in `TextField1</api/user_interface/desktop/desktoptextfield>` to the text file that was opened by `FolderItem<folderitem.showopenfiledialog>`:
>
> ``` xojo
> 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
> ```

<div id="textoutputstream.write">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

TextOutputStream.Write

**Write**(Line As `String</api/data_types/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<writeable.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<writeable.flush>` method to reduce latencies that this buffering may cause in such cases.
>
> If Write fails, an `IOException</api/exceptions/ioexception>` will be raised.
>
> This example displays the Save As dialog box and writes the contents of the TextArea1 to a text file.
>
> ``` xojo
> 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
> ```

<div id="textoutputstream.writeline">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

TextOutputStream.WriteLine

**WriteLine**(Line As `String</api/data_types/string>` = "")

> Writes the data `Line` passed to the <span class="title-ref">TextOutputStream</span> and appends the *Delimiter* to the end of the line.
>
> If WriteLine fails, an `IOException</api/exceptions/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</api/user_interface/desktop/desktoptextfield>` are written to the new file. Finally the file is closed.
>
> ``` xojo
> 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

This class implements the `Writeable</api/files/writeable>` class interface.

## Notes

### Setting the text encoding

The default encoding is UTF8. If you want no encoding, use a `BinaryStream</api/files/binarystream>`. If you need to write a file using a different encoding, use the `Encoding<textoutputstream.encoding>` property before passing the text to the Write or WriteLine methods.

``` xojo
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</api/text/encoding_text/encodings>` module.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Creating and appending to a text file

Use `Open<textoutputstream.open>` when you want to open an existing text file and add text data to it. Use `Create<textoutputstream.create>` to write to a new text file. The following two examples illustrate the difference. Each example writes the text in `TextField1</api/user_interface/desktop/desktoptextfield>` to the text file.

This code appends the text in `TextField1</api/user_interface/desktop/desktoptextfield>` to the text file that was opened by `FolderItem<folderitem.showopenfiledialog>`:

``` xojo
Var file As FolderItem = FolderItem.ShowOpenFileDialog(FileTypes1.Text)

If file <> Nil then
  Var output As TextOutputStream    
  output = TextOutputStream.Open(file)
  output.Write(TextField1.Text)
  output.Close
End If
```

This code writes to a new text file.

``` xojo
Var file As FolderItem = FolderItem.ShowSaveFileDialog("", "CreateExample.txt")

If file <> Nil Then
  Var output As TextOutputStream    
  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</api/user_interface/desktop/desktoptextfield>` are written to the new file. Finally the file is closed.

``` xojo
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

|                       |     |
|-----------------------|-----|
| **Project Types**     | All |
| **Operating Systems** | All |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `BinaryStream</api/files/binarystream>`, `FolderItem</api/files/folderitem>`, `IOException</api/exceptions/ioexception>`, `TextInputStream</api/files/textinputstream>` classes; `ConvertEncoding</api/text/encoding_text/convertencoding>` function; `Encodings</api/text/encoding_text/encodings>` module; `Writeable</api/files/writeable>` class interface.

</div>