ftextinput

Read text file

Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

Syntax

ftextinput(filename | n, <Encoding = "encodingValue">)
ftextinput(filename | n, x1, x2, …, <Encoding = "encodingValue">)

Description

ftextinput(file, x) reads a line from a text file, interprets the line as a string and assigns this string to the identifier x.

ftextinput(filename) reads the first line of the text file and returns it as a string to the MuPAD® session. If the file is in gzip-compressed format and its name ends in ".gz", it will be transparently uncompressed upon reading.

ftextinput(filename, x1, x2, ...) reads the file line by line. The i-th line is converted to a character string and assigned to the identifier xi. The identifiers are not evaluated while executing ftextinput; previously assigned values are overwritten.

fread(..., Encoding = "encodingValue") uses the specified encoding. For the supported encodings, see Options. You can use this option with any of the previously specified syntaxes.

Instead of a file name, also a file descriptor n of a file opened via fopen can be used. The functionality is as described above. However, there is one difference: With a file name, ftextinput automatically opens the file, performs the operation, and closes the file. A subsequent call to ftextinput starts at the beginning of the file. With a file descriptor, the file remains open (use fclose to close the file). The next time data are read from this file, the reading continues at the current position. Consequently, a file descriptor should be used, if the individual lines in the file are to be read via several subsequent calls of ftextinput. Cf. Example 2.

If the number of identifiers specified in the ftextinput call is larger than the number of lines in the file, the exceeding identifiers are not assigned any values. In such a case, ftextinput returns the void object of type DOM_NULL.

ftextinput interprets the file name as a pathname relative to the "working directory."

Note that the meaning of "working directory" depends on the operating system. On Windows® systems and on Mac OS X systems, the "working directory" is the folder where MATLAB® is installed. On UNIX® systems, it is the current working directory in which MATLAB was started. When started from a menu or desktop item, this is typically the user's home directory.

Also absolute path names are processed by ftextinput.

Expression sequences are not flattened by ftextinput and cannot be used to pass several identifiers to ftextinput. Cf. Example 3.

Examples

Example 1

Use fprint to create a text file with three lines:

fid := fopen(TempFile, Write, Text):
fprint(Unquoted, fid, "x + 1\n2nd line\n3rd line"):
file := fname(fid):

Read the first two lines of the file and assign the corresponding strings to the identifiers x1 and x2:

ftextinput(file, x1, x2):
x1, x2

If you try to read beyond the last line of the file, ftextinput returns the void object of type DOM_NULL:

ftextinput(file, x1, x2, x3, x4); domtype(%)

x1, x2, x3, x4

delete x1, x2, x3:

Example 2

Read some lines from a file using several calls of ftextinput. You have to use a file descriptor for reading from the file. The file is opened for reading with fopen:

fid := fopen(TempFile, Write, Text):
fprint(Unquoted, fid, 
       "x + 1\nx + 2\n3rd line\n4th line"):
file := fname(fid):
n := fopen(file):

The file descriptor returned by fopen can be passed to ftextinput for reading the data:

ftextinput(n, x1, x2):
x1, x2

ftextinput(n, x3, x4):
x3, x4

Finally, close the file and delete the identifiers:

fclose(n):
delete n, x1, x2, x3, x4:

Alternatively, the contents of a file can be read into a MuPAD session in the following way:

n := fopen(file):
for i from 1 to 4 do
   x.i := ftextinput(n)
end_for:
x1, x2, x3, x4

fclose(n):
delete n, i, x1, x2, x3, x4:

Example 3

Expression sequences are not flattened by ftextinput and cannot be used to pass identifiers to ftextinput:

fid := fopen(TempFile, Write, Text):
fprint(Unquoted, fid, "1st line\n2nd line\n3rd line"):
file := fname(fid):
ftextinput(file, (x1, x2), x3)
Error: The argument is invalid. [ftextinput]

The following call does not lead to an error because the identifier x12 is not evaluated. Consequently, only one line is read from the file and assigned to x12:

x12 := x1, x2:
ftextinput(file, x12):
x1, x2, x12

delete x12:

Example 4

To specify the encoding for reading data, use Encoding. The Encoding option applies only to text files that are opened using a file name and not a file descriptor. Open a temporary file and write the string "abcäöü" in the encoding "UTF-8":

fprint(Unquoted, Text, Encoding = "UTF-8",
                       "ftextinput_test",
                       "abcäöü"):

Specify the encoding to read the file correctly:

ftextinput("ftextinput_test", Encoding="UTF-8")

If you do not specify an encoding, the default system encoding is used. Thus, your output might vary from that shown next. Characters unrecognized by the default system encoding are replaced by the default substitution character for that encoding:

ftextinput("ftextinput_test")

Parameters

filename

The name of a file: a character string

n

A file descriptor provided by fopen: a positive integer

x1, x2, …

identifiers

Options

Encoding

This option lets you specify the character encoding to use. The allowed encodings are:

"Big5"

"ISO-8859-1"

"windows-932"

"EUC-JP"

"ISO-8859-2"

"windows-936"

"GBK"

"ISO-8859-3"

"windows-949"

"KSC_5601"

"ISO-8859-4"

"windows-950"

"Macintosh"

"ISO-8859-9"

"windows-1250"

"Shift_JIS"

"ISO-8859-13"

"windows-1251"

"US-ASCII"

"ISO-8859-15"

"windows-1252"

"UTF-8"

 

"windows-1253"

  

"windows-1254"

  

"windows-1257"

The default encoding is system dependent. If you specify the encoding incorrectly, characters might read incorrectly. Characters unrecognized by the encoding are replaced by the default substitution character for the specified encoding.

Encodings not listed here can be specified but might not produce correct results.

Return Values

Last line that was read from the file: a character string or null().

Was this topic helpful?