Package Modelica.Utilities.StreamsRead from files and write to files
Package Modelica.Utilities.Streams
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/type | Description |
|---|---|
| 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).
| Name | Description |
|---|---|
close | Close file |
countLines | Return the number of lines in a file |
error | Print error message and cancel all actions - in case of an unrecoverable error |
print | Print string to terminal or file |
readFile | Read content of a file and return it in a vector of strings |
readLine | Read a line of text from a file and return it in a string |
readMatrixSize | Read dimensions of a Real matrix from a MATLAB MAT file |
readRealMatrix | Read Real matrix from MATLAB MAT file |
writeRealMatrix | Write Real matrix to a MATLAB MAT file |
Function Modelica.Utilities.Streams.print
Streams.print(string); Streams.print(string,fileName);
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.
Streams.print("x = " + String(x));
Streams.print("y = " + String(y));
Streams.print("x = " + String(y), "mytestfile.txt");
Streams, Streams.error, ModelicaReference.Operators.'String()'
Extends from Modelica.Icons.Function (Icon for functions).
| Type | Name | Description |
|---|---|---|
String | string | String to be printed |
String | fileName | File where to print (empty string is the terminal) |
Function Modelica.Utilities.Streams.readFile
stringVector = Streams.readFile(fileName)
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).
| Type | Name | Description |
|---|---|---|
String | fileName | Name of the file that shall be read |
| Type | Name | Description |
|---|---|---|
String | stringVector[countLines(fileName)] | Content of file |
Function Modelica.Utilities.Streams.readLine
(string, endOfFile) = Streams.readLine(fileName, lineNumber)
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).
| Type | Name | Description |
|---|---|---|
String | fileName | Name of the file that shall be read |
Integer | lineNumber | Number of line to read |
| Type | Name | Description |
|---|---|---|
String | string | Line of text |
Boolean | endOfFile | If true, end-of-file was reached when trying to read line |
Function Modelica.Utilities.Streams.countLines
numberOfLines = Streams.countLines(fileName)
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).
| Type | Name | Description |
|---|---|---|
String | fileName | Name of the file that shall be read |
| Type | Name | Description |
|---|---|---|
Integer | numberOfLines | Number of lines in file |
Function Modelica.Utilities.Streams.error
Streams.error(string);
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.
Streams.error("x (= " + String(x) + ")\nhas to be in the range 0 .. 1");
Streams, Streams.print, ModelicaReference.Operators.'assert()' ModelicaReference.Operators.'String()'
Extends from Modelica.Icons.Function (Icon for functions).
| Type | Name | Description |
|---|---|---|
String | string | String to be printed to error message window |
Function Modelica.Utilities.Streams.close
Streams.close(fileName)
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).
| Type | Name | Description |
|---|---|---|
String | fileName | Name of the file that shall be closed |
Function Modelica.Utilities.Streams.readMatrixSize
dim = Streams.readMatrixSize(fileName, matrixName)
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.
See Examples.ReadRealMatrixFromFile.
readRealMatrix, writeRealMatrix
Extends from Modelica.Icons.Function (Icon for functions).
| Type | Name | Description |
|---|---|---|
String | fileName | File where external data is stored |
String | matrixName | Name / identifier of the 2D Real array on the file |
| Type | Name | Description |
|---|---|---|
Integer | dim[2] | Number of rows and columns of the 2D Real array |
Function Modelica.Utilities.Streams.readRealMatrix
matrix = Streams.readRealMatrix(fileName, matrixName, nrow, ncol, verboseRead)
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.
See Examples.ReadRealMatrixFromFile.
readMatrixSize, writeRealMatrix
Extends from Modelica.Icons.Function (Icon for functions).
| Type | Name | Description |
|---|---|---|
String | fileName | File where external data is stored |
String | matrixName | Name / identifier of the 2D Real array on the file |
Integer | nrow | Number of rows of the 2D Real array |
Integer | ncol | Number of columns of the 2D Real array |
Boolean | verboseRead | = true: Print info message; = false: No info message |
| Type | Name | Description |
|---|---|---|
Real | matrix[nrow,ncol] | 2D Real array |
Function Modelica.Utilities.Streams.writeRealMatrix
success = Streams.writeRealMatrix(fileName, matrixName, matrix, append, format)
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.
See Examples.WriteRealMatrixToFile.
readMatrixSize, readRealMatrix
Extends from Modelica.Icons.Function (Icon for functions).
| Type | Name | Description |
|---|---|---|
String | fileName | File where external data is to be stored |
String | matrixName | Name / identifier of the 2D Real array on the file |
Real | matrix[:,:] | 2D Real array |
Boolean | append | Append values to file |
String | format | MATLAB MAT file version: "4" -> v4, "6" -> v6, "7" -> v7 |
| Type | Name | Description |
|---|---|---|
Boolean | success | true if successful |