Package 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 Contents

NameDescription
closeClose file
countLinesReturn the number of lines in a file
errorPrint error message and cancel all actions - in case of an unrecoverable error
printPrint string to terminal or file
readFileRead content of a file and return it in a vector of strings
readLineRead a line of text from a file and return it in a string
readMatrixSizeRead dimensions of a Real matrix from a MATLAB MAT file
readRealMatrixRead Real matrix from MATLAB MAT file
writeRealMatrixWrite Real matrix to a MATLAB MAT file

Function 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

TypeNameDescription
StringstringString to be printed
StringfileNameFile where to print (empty string is the terminal)

Function 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

TypeNameDescription
StringfileNameName of the file that shall be read

Outputs

TypeNameDescription
StringstringVector[countLines(fileName)]Content of file

Function 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

TypeNameDescription
StringfileNameName of the file that shall be read
IntegerlineNumberNumber of line to read

Outputs

TypeNameDescription
StringstringLine of text
BooleanendOfFileIf true, end-of-file was reached when trying to read line

Function 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

TypeNameDescription
StringfileNameName of the file that shall be read

Outputs

TypeNameDescription
IntegernumberOfLinesNumber of lines in file

Function 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

TypeNameDescription
StringstringString to be printed to error message window

Function 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

TypeNameDescription
StringfileNameName of the file that shall be closed

Function 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

TypeNameDescription
StringfileNameFile where external data is stored
StringmatrixNameName / identifier of the 2D Real array on the file

Outputs

TypeNameDescription
Integerdim[2]Number of rows and columns of the 2D Real array

Function 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

TypeNameDescription
StringfileNameFile where external data is stored
StringmatrixNameName / identifier of the 2D Real array on the file
IntegernrowNumber of rows of the 2D Real array
IntegerncolNumber of columns of the 2D Real array
BooleanverboseRead= true: Print info message; = false: No info message

Outputs

TypeNameDescription
Realmatrix[nrow,ncol]2D Real array

Function 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

TypeNameDescription
StringfileNameFile where external data is to be stored
StringmatrixNameName / identifier of the 2D Real array on the file
Realmatrix[:,:]2D Real array
BooleanappendAppend values to file
StringformatMATLAB MAT file version: "4" -> v4, "6" -> v6, "7" -> v7

Outputs

TypeNameDescription
Booleansuccesstrue if successful

Generated 2018-12-12 12:14:36 EST by MapleSim.