finput

Read objects from file

Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

Syntax

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

Description

finput(filename, x) reads a MuPAD® object from a file and assigns it to the identifier x.

finput(n, x) reads from the file associated with the file descriptor n.

finput can read MuPAD binary files as well as ASCII text files. finput recognizes the format of the file automatically.

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

Binary files may be created via fprint or write. Text files can also be created in a MuPAD session via these functions (using the Text option; see the corresponding help pages for details). Alternatively, text files can be created and edited directly using your favorite text editor. The file must consist of syntactically correct MuPAD objects or statements, separated by semicolons or colons. An object may extend over more than one line.

finput(filename) reads the first object in the file and returns it to the MuPAD session.

finput(filename, x1, x2, ...) reads the contents of a file object by object. The i-th object is assigned to the identifier xi. The identifiers are not evaluated while executing finput; previously assigned values are overwritten. The objects are not evaluated. Evaluation can be enforced with the function eval. Cf. Example 2.

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, the file is closed automatically after the data were read. A subsequent call to finput 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 objects in the file are to be read via several subsequent calls of finput. Cf. Example 3.

Files in gzip compressed format with a filename ending in ".gz" are automatically and transparently decompressed while reading.

If the number of identifiers specified in the finput call is larger than the number of objects in the file, the additional identifiers are assigned the value null().

finput interprets the file name as a pathname relative to the "working folder."

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

Also absolute path names are processed by finput.

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

Examples

Example 1

Create a new file in the system's temporary folder. The name of the temporary folder varies for different platforms. The fopen command with the TempFile option creates a file in any system's temporary folder (if such folder exists):

fid := fopen(TempFile, Write, Text):

Write the numbers 11, 22, 33 and 44 into a file:

fprint(fid, 11, 22, 33, 44):

Use fname to return the name of the temporary file you created:

file := fname(fid):

Read this file with finput:

finput(file, x1, x2, x3, x4)

x1, x2, x3, x4

If you try to read more objects than stored in the file, finput returns the void object of type DOM_NULL:

finput(file, x1, x2, x3, x4, x5); domtype(%)

delete x1, x2, x3, x4, x5:

Example 2

Objects read from a file are not evaluated:

fid := fopen(TempFile, Write, Text):
file := fname(fid):
fprint(file, x1):
x1 := 23:
finput(file)

eval(%)

delete x1:

Example 3

Read some data from a file using several calls of finput. 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(fid, 11, 22, 33, 44):
file := fname(fid):
n := fopen(file):

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

finput(n, x1, x2): x1, x2

finput(n, x3, x4):
x3, x4

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 := finput(n)
end_for:
x1, x2, x3, x4

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

Example 4

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

fid := fopen(TempFile, Write, Text):
fprint(fid, 11, 22, 33):
file := fname(fid):
finput(file, (x1, x2), x3)
Error: The argument is invalid. [finput]

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

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

delete x1, x2, x12:

Example 5

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

fprint(Text, Encoding="UTF-8", "finput_test", "abcäöü", 11, 22):

Specify the encoding to read the stored values correctly:

finput("finput_test", Encoding="UTF-8", x1, x2, x3):
x1, x2, x3

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:

finput("finput_test", x1, x2, x3):
x1, x2, x3

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 object that was read from the file.

See Also

MuPAD Functions

Was this topic helpful?