Modelica.Utilities.Streams

Read from files and write to files

Information

Library content

Package Streams contains functions to input and output strings to a message window or on files, as well as reading matrices from file and writing matrices to file. Note that a string is interpreted and displayed as html text (e.g., with print(..) or error(..)) if it is enclosed with the Modelica html quotation, e.g.,

string = "<html> first line <br> second line </html>".

It is a quality of implementation, whether (a) all tags of html are supported or only a subset, (b) how html tags are interpreted if the output device does not allow to display formatted text.

In the table below an example call to every function is given:

Function/typeDescription
print(string)
print(string,fileName)		 Print string "string" or vector of strings to message window or on file "fileName".
stringVector = readFile(fileName) Read complete text file and return it as a vector of strings.
(string, endOfFile) = readLine(fileName, lineNumber) Returns from the file the content of line lineNumber.
lines = countLines(fileName) Returns the number of lines in a file.
error(string) Print error message "string" to message window and cancel all actions
close(fileName) Close file if it is still open. Ignore call if file is already closed or does not exist.
readMatrixSize(fileName, matrixName) Read dimensions of a Real matrix from a MATLAB MAT file.
readRealMatrix(fileName, matrixName, nrow, ncol) Read a Real matrix from a MATLAB MAT file.
writeRealMatrix(fileName, matrixName, matrix, append, format) Write Real matrix to a MATLAB MAT file.

Use functions scanXXX from package Strings to parse a string.

If Real, Integer or Boolean values shall be printed or used in an error message, they have to be first converted to strings with the builtin operator ModelicaReference.Operators.'String()'(...). Example: 

if x < 0 or x > 1 then
   Streams.error("x (= " + String(x) + ") has to be in the range 0 .. 1");
end if;

Extends from Modelica.Icons.FunctionsPackage (Icon for packages containing functions).

Package Content

Name Description
Modelica.Utilities.Streams.print print Print string to terminal or file
Modelica.Utilities.Streams.readFile readFile Read content of a file and return it in a vector of strings
Modelica.Utilities.Streams.readLine readLine Read a line of text from a file and return it in a string
Modelica.Utilities.Streams.countLines countLines Return the number of lines in a file
Modelica.Utilities.Streams.error error Print error message and cancel all actions - in case of an unrecoverable error
Modelica.Utilities.Streams.close close Close file
Modelica.Utilities.Streams.readMatrixSize readMatrixSize Read dimensions of a Real matrix from a MATLAB MAT file
Modelica.Utilities.Streams.readRealMatrix readRealMatrix Read Real matrix from MATLAB MAT file
Modelica.Utilities.Streams.writeRealMatrix writeRealMatrix Write Real matrix to a MATLAB MAT file

Modelica.Utilities.Streams.print Modelica.Utilities.Streams.print

Print string to terminal or file

Information

Syntax

Streams.print(string);
Streams.print(string,fileName);

Description

Function print(..) opens automatically the given file, if it is not yet open. If the file does not exist, it is created. If the file does exist, the given string is appended to the file. If this is not desired, call "Files.remove(fileName)" before calling print ("remove(..)" is silent, if the file does not exist). The Modelica environment may close the file whenever appropriate. This can be enforced by calling Streams.close(fileName). After every call of "print(..)" a "new line" is printed automatically.

Example

Streams.print("x = " + String(x));
Streams.print("y = " + String(y));
Streams.print("x = " + String(y), "mytestfile.txt");

See also

Streams, Streams.error, ModelicaReference.Operators.'String()'

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

NameDescription
stringString to be printed
fileNameFile where to print (empty string is the terminal)

Modelica.Utilities.Streams.readFile Modelica.Utilities.Streams.readFile

Read content of a file and return it in a vector of strings

Information

Syntax

stringVector = Streams.readFile(fileName)

Description

Function readFile(..) opens the given file, reads the complete content, closes the file and returns the content as a vector of strings. Lines are separated by LF or CR-LF; the returned strings do not contain the line separators. Note, a fileName can be defined as URI by using the helper function loadResource.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

NameDescription
fileNameName of the file that shall be read

Outputs

NameDescription
stringVector[countLines(fileName)]Content of file

Modelica.Utilities.Streams.readLine Modelica.Utilities.Streams.readLine

Read a line of text from a file and return it in a string

Information

Syntax

(string, endOfFile) = Streams.readLine(fileName, lineNumber)

Description

Function readLine(..) opens the given file, reads enough of the content to get the requested line, and returns the line as a string. Lines are separated by LF or CR-LF; the returned string does not contain the line separator. The file might remain open after the call.

If lineNumber > countLines(fileName), an empty string is returned and endOfFile=true. Otherwise endOfFile=false.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

NameDescription
fileNameName of the file that shall be read
lineNumberNumber of line to read

Outputs

NameDescription
stringLine of text
endOfFileIf true, end-of-file was reached when trying to read line

Modelica.Utilities.Streams.countLines Modelica.Utilities.Streams.countLines

Return the number of lines in a file

Information

Syntax

numberOfLines = Streams.countLines(fileName)

Description

Function countLines(..) opens the given file, reads the complete content, closes the file and returns the number of lines. Lines are separated by LF or CR-LF.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

NameDescription
fileNameName of the file that shall be read

Outputs

NameDescription
numberOfLinesNumber of lines in file

Modelica.Utilities.Streams.error Modelica.Utilities.Streams.error

Print error message and cancel all actions - in case of an unrecoverable error

Information

Syntax

Streams.error(string);

Description

In case of an unrecoverable error (i.e., if the solver is unable to recover from the error), print the string "string" as error message and cancel all actions. This function is semantically equivalent with the built-in function assert if called with the (default) AssertionLevel.error. Line breaks are characterized by "\n" in the string.

Example

Streams.error("x (= " + String(x) + ")\nhas to be in the range 0 .. 1");

See also

Streams, Streams.print, ModelicaReference.Operators.'assert()' ModelicaReference.Operators.'String()'

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

NameDescription
stringString to be printed to error message window

Modelica.Utilities.Streams.close Modelica.Utilities.Streams.close

Close file

Information

Syntax

Streams.close(fileName)

Description

Close file if it is open. Ignore call if file is already closed or does not exist.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

NameDescription
fileNameName of the file that shall be closed

Modelica.Utilities.Streams.readMatrixSize Modelica.Utilities.Streams.readMatrixSize

Read dimensions of a Real matrix from a MATLAB MAT file

Information

Syntax

dim = Streams.readMatrixSize(fileName, matrixName)

Description

Function readMatrixSize(..) opens the given MATLAB MAT file (in format v4, v6, v7, and if HDF is supported in the Modelica tool, also v7.3), and reads the dimensions of the given Real matrix. These dimensions are returned in the Integer vector dim.

Example

See Examples.ReadRealMatrixFromFile.

See also

readRealMatrix, writeRealMatrix

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

NameDescription
fileNameFile where external data is stored
matrixNameName / identifier of the 2D Real array on the file

Outputs

NameDescription
dim[2]Number of rows and columns of the 2D Real array

Modelica.Utilities.Streams.readRealMatrix Modelica.Utilities.Streams.readRealMatrix

Read Real matrix from MATLAB MAT file

Information

Syntax

matrix = Streams.readRealMatrix(fileName, matrixName, nrow, ncol, verboseRead)

Description

Function readRealMatrix(..) opens the given MATLAB MAT file (in format v4, v6, v7, and if HDF is supported in the Modelica tool, also v7.3), and reads the given matrix from this file. The dimensions of this matrix must first be inquired with function readMatrixSize and passed via arguments nrow and ncol to this function.

Example

See Examples.ReadRealMatrixFromFile.

See also

readMatrixSize, writeRealMatrix

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

NameDescription
fileNameFile where external data is stored
matrixNameName / identifier of the 2D Real array on the file
nrowNumber of rows of the 2D Real array
ncolNumber of columns of the 2D Real array
verboseRead= true: Print info message; = false: No info message

Outputs

NameDescription
matrix[nrow, ncol]2D Real array

Modelica.Utilities.Streams.writeRealMatrix Modelica.Utilities.Streams.writeRealMatrix

Write Real matrix to a MATLAB MAT file

Information

Syntax

success = Streams.writeRealMatrix(fileName, matrixName, matrix, append, format)

Description

Function writeRealMatrix(..) writes the given matrix to a new or an existing MATLAB MAT file (in format v4, v6, v7, and if HDF is supported in the Modelica tool, also v7.3). If append = false (= default), the file is newly created (or an existing file is deleted and re-created). If append = true, the matrix is included in an existing file or if the file does not yet exists this flag is ignored. If the file exists and append = true, argument format is ignored.

Parameter format defines the format in which the values are stored on file. The following formats are supported:
 

format = Type of format
"4" MATLAB MAT version v4
"6" MATLAB MAT version v6
"7" MATLAB MAT version v7
"7.3"MATLAB MAT version v7.3
(requires HDF support in the Modelica tool)

The function returns success = true if the matrix was successfully written to file. Otherwise, an error message is printed and the function returns with success = false.

Example

See Examples.WriteRealMatrixToFile.

See also

readMatrixSize, readRealMatrix

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

NameDescription
fileNameFile where external data is to be stored
matrixNameName / identifier of the 2D Real array on the file
matrix[:, :]2D Real array
appendAppend values to file
formatMATLAB MAT file version: "4" -> v4, "6" -> v6, "7" -> v7

Outputs

NameDescription
successtrue if successful
Automatically generated Thu Oct 1 16:08:16 2020.