.. highlightlang:: us

.. index:: text_file_write

.. _text_file_write:

text_file_write
===============

.. us.tag  text_file_write ENGLISH FILE_MISC unicode New500 Changed5501

:ref:`text_file_write` writes text into a file in ANSI - or Unicode format.

.. function::  bool = text_file_write(ssFilename, ssText)
               bool = text_file_write(ssFilename, ssText, ssEncoding)
               bool = text_file_write(ssFilename, ssText, ssEncoding, ssNewline)

.. us.return

**Return Value**

Returns TRUE (1) if successful, FALSE (0) otherwise.

.. us.params

**Parameters**

.. uparam:: ssFilename

   *ssFilename* is the complete file name. If the file already exists the file
   will be overwritten.

.. uparam:: ssText

   *ssText* is the text.

.. uparam:: ssEncoding

   *ssEncoding* is one of the following strings:

   .. list-table::
      :header-rows: 1

      * - Value
        - Meaning
      * - ansi
        - default value
      * - utf8bom
        - UTF-8 with BOM (Byte Order Mark).
      * - utf8
        - UTF-8 without BOM.
      * - utf16le
        - UTF-16 little endian without BOM.
      * - utf16lebom
        - UTF-16 little endian with BOM.
      * - utf16
        - UTF-16 without BOM.
      * - utf16bom
        - UTF-16 with BOM.

   The values are case insensitive and minus characters are ignored.
   ``UTF-16-LE`` is a valid value.

.. uparam:: ssNewline

   *ssNewline* is one of the following strings:

   .. list-table::
      :header-rows: 1

      * - Value
        - Meaning
      * - "default"
        - Default value ("crlf")
      * - "crlf"
        - ``\x0d \x0a``
      * - "cr"
        - ``\x0d``
      * - "lf"
        - ``\x0a``

.. us.example

**Example**

::

   ssText = "[[This is
   a text]]";
   text_file_write("c:/test.txt", ssText, "ansi", "default")

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - R2013.1
     - The parameter *ssEncoding* may contain ``-`` characters, e. g.
       ``utf-8``.
   * - 5.0.0
     - New.

.. seealso::
   :ref:`overview-binary-and-text-files`,
   :ref:`text_file_read`

:sub:`id-847459`